feat(desktop): custom in-app window title bar on Windows (#7781)

<img width="1750" height="1223" alt="image"
src="https://github.com/user-attachments/assets/c115a30c-be62-4eaa-8de3-26a93a605919"
/>

## Custom windows top bar
* Doesn't work on mac
* doesn't effect web 
* little effort been put into mobile view

.gitignore

@@ -312,3 +312,4 @@ docs/type3/signatures/
 
 # Local screenshot artifacts from *-screenshots.spec.ts
 frontend/editor/screenshots/
+frontend/editor/src-tauri/libs/.variant

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

@@ -25,4 +25,7 @@ public class AiWorkflowRequest {
                     "Prior chat messages exchanged between the user and the assistant, ordered"
                             + " oldest-first. Excludes the current userMessage.")
     private List<AiConversationMessage> conversationHistory = new ArrayList<>();
+
+    @Schema(description = "IETF language tag the reply should be written in", example = "fr-FR")
+    private String locale;
 }

app/proprietary/src/main/java/stirling/software/proprietary/policy/controller/PolicyController.java

@@ -398,6 +398,8 @@ public class PolicyController {
                 policy.name(),
                 owner,
                 policy.enabled(),
+                policy.required(),
+                policy.icon(),
                 policy.inputs(),
                 policy.steps(),
                 policy.output(),

app/proprietary/src/main/java/stirling/software/proprietary/policy/model/Policy.java

@@ -21,6 +21,8 @@ public record Policy(
         String name,
         String owner,
         boolean enabled,
+        boolean required,
+        String icon,
         List<PipelineInput> inputs,
         List<PipelineStep> steps,
         OutputSpec output,
@@ -29,6 +31,7 @@ public record Policy(
         EditorConfig editor) {
 
     public Policy {
+        icon = icon == null ? "" : icon;
         inputs = inputs == null ? List.of() : List.copyOf(inputs);
         steps = steps == null ? List.of() : steps;
         output = output == null ? OutputSpec.inline() : output;
@@ -36,7 +39,11 @@ public record Policy(
         editor = editor == null ? EditorConfig.disabled() : editor;
     }
 
-    /** Without editor participation: a swept or on-demand policy. */
+    /**
+     * Without the {@code required} flag, {@code icon}, or editor participation: defaults to not
+     * org-required, no icon, and a swept/on-demand policy. Kept for the many callers and tests
+     * written before those fields; the frontend and stores that care use the full constructor.
+     */
     public Policy(
             String id,
             String name,
@@ -47,7 +54,26 @@ public record Policy(
             OutputSpec output,
             List<String> outputIds,
             Long teamId) {
-        this(id, name, owner, enabled, inputs, steps, output, outputIds, teamId, null);
+        this(id, name, owner, enabled, false, "", inputs, steps, output, outputIds, teamId, null);
+    }
+
+    /**
+     * Without the {@code required} flag or {@code icon} but with explicit editor participation: the
+     * seeded Classification policy runs on the editor, so it must set {@link EditorConfig} even
+     * though it predates the org-required and icon fields.
+     */
+    public Policy(
+            String id,
+            String name,
+            String owner,
+            boolean enabled,
+            List<PipelineInput> inputs,
+            List<PipelineStep> steps,
+            OutputSpec output,
+            List<String> outputIds,
+            Long teamId,
+            EditorConfig editor) {
+        this(id, name, owner, enabled, false, "", inputs, steps, output, outputIds, teamId, editor);
     }
 
     /**
@@ -108,19 +134,32 @@ public record Policy(
     /** A copy with the inline output replaced (e.g. resolved for the engine, or migrated). */
     public Policy withOutput(OutputSpec resolved) {
         return new Policy(
-                id, name, owner, enabled, inputs, steps, resolved, outputIds, teamId, editor);
+                id, name, owner, enabled, required, icon, inputs, steps, resolved, outputIds,
+                teamId, editor);
     }
 
     /** A copy under a different owner (e.g. moving a seed off a placeholder name). */
     public Policy withOwner(String newOwner) {
         return new Policy(
-                id, name, newOwner, enabled, inputs, steps, output, outputIds, teamId, editor);
+                id, name, newOwner, enabled, required, icon, inputs, steps, output, outputIds,
+                teamId, editor);
     }
 
     /** A copy referencing the given saved output destinations. */
     public Policy withOutputIds(List<String> newOutputIds) {
         return new Policy(
-                id, name, owner, enabled, inputs, steps, output, newOutputIds, teamId, editor);
+                id,
+                name,
+                owner,
+                enabled,
+                required,
+                icon,
+                inputs,
+                steps,
+                output,
+                newOutputIds,
+                teamId,
+                editor);
     }
 
     /**

app/proprietary/src/main/java/stirling/software/proprietary/policy/overview/PolicyOverviewService.java

@@ -20,28 +20,23 @@ import stirling.software.proprietary.policy.source.SourceStore;
 import stirling.software.proprietary.policy.store.PolicyStore;
 
 /**
- * Builds the Pipelines overview: one row per policy the caller's team built on the Pipelines page,
- * with its sources resolved to live display names, its steps, and a trigger/output summary.
- * Frontend/catalogue policies (marked by a {@code categoryId} in their output options) belong to
- * the user-facing Policies page and are excluded; a folder-watch trigger is not a signal.
+ * Builds the unified Pipelines overview: one row per policy the caller's team owns, with its
+ * sources resolved to live display names, its steps, and a trigger/output summary. This lists EVERY
+ * policy - both pipelines built in the full builder and the friendly "suggested" policies - since
+ * the two surfaces were merged (a policy is a pipeline the org requires). No catalogue filter any
+ * more.
  */
 @Service
 @RequiredArgsConstructor
 public class PolicyOverviewService {
 
-    // Output-options key marking a frontend/catalogue policy (set by the Policies page and seeder).
-    private static final String CATEGORY_OPTION = "categoryId";
-
     private final PolicyStore policyStore;
     private final SourceStore sourceStore;
     private final PolicyAccessGuard policyAccessGuard;
     private final SourceAccessGuard sourceAccessGuard;
 
     public PoliciesOverviewResponse overview() {
-        List<Policy> policies =
-                policyAccessGuard.visibleFrom(policyStore).stream()
-                        .filter(PolicyOverviewService::isPipeline)
-                        .toList();
+        List<Policy> policies = policyAccessGuard.visibleFrom(policyStore).stream().toList();
         Map<String, String> sourceNames = sourceNames();
 
         List<PolicyView> views =
@@ -55,18 +50,6 @@ public class PolicyOverviewService {
         return new PoliciesOverviewResponse(buildKpis(policies), views);
     }
 
-    private static boolean isPipeline(Policy policy) {
-        return !isCataloguePolicy(policy);
-    }
-
-    /** A frontend/catalogue policy, marked by a {@code categoryId} in its output options. */
-    private static boolean isCataloguePolicy(Policy policy) {
-        OutputSpec output = policy.output();
-        return output != null
-                && output.options().get(CATEGORY_OPTION) instanceof String category
-                && !category.isBlank();
-    }
-
     /** Display names for every source the caller's team can see, keyed by source id. */
     private Map<String, String> sourceNames() {
         Map<String, String> names = new HashMap<>();
@@ -88,6 +71,8 @@ public class PolicyOverviewService {
                 policy.id(),
                 policy.name(),
                 policy.enabled(),
+                policy.required(),
+                iconKey(policy),
                 policy.enabled() ? "active" : "paused",
                 triggerSummary(policy),
                 sources,
@@ -111,6 +96,25 @@ public class PolicyOverviewService {
         return outputSummary(policy.output());
     }
 
+    /**
+     * The list-row icon key. The policy's first-class {@code icon} wins; otherwise a
+     * template-derived policy falls back to its {@code categoryId} (the template-identity marker
+     * the frontend maps to the category glyph). Empty when neither is set, so the frontend shows
+     * its default.
+     */
+    private static String iconKey(Policy policy) {
+        if (!policy.icon().isBlank()) {
+            return policy.icon();
+        }
+        OutputSpec output = policy.output();
+        if (output != null
+                && output.options().get("categoryId") instanceof String category
+                && !category.isBlank()) {
+            return category;
+        }
+        return "";
+    }
+
     /**
      * Summarise a policy's triggers for the overview row: "manual" when no input is triggered,
      * otherwise the distinct trigger types across its inputs (e.g. "folder-watch, schedule").

app/proprietary/src/main/java/stirling/software/proprietary/policy/overview/PolicyView.java

@@ -3,15 +3,18 @@ package stirling.software.proprietary.policy.overview;
 import java.util.List;
 
 /**
- * One row in the Pipelines overview: a stored policy shown for the admin portal, with its
- * referenced sources resolved to names and its pipeline summarised. The portal's "all pipelines"
- * surface lists every backend policy (the user-facing Policies page builds only a friendly subset
- * of these).
+ * One row in the unified Pipelines overview: a stored policy shown for the admin portal, with its
+ * referenced sources resolved to names and its pipeline summarised. This surface lists every
+ * backend policy - both the pipelines built in the full builder and the friendly "suggested"
+ * policies - so a {@code required} policy (one the org mandates) reads the same as any other
+ * pipeline here.
  */
 public record PolicyView(
         String id,
         String name,
         boolean enabled,
+        boolean required,
+        String icon,
         String status,
         String trigger,
         List<SourceRef> sources,

app/proprietary/src/main/java/stirling/software/proprietary/policy/store/InProcessPolicyStore.java

@@ -34,6 +34,8 @@ public class InProcessPolicyStore implements PolicyStore {
                         policy.name(),
                         policy.owner(),
                         policy.enabled(),
+                        policy.required(),
+                        policy.icon(),
                         policy.inputs(),
                         policy.steps(),
                         policy.output(),

app/proprietary/src/main/java/stirling/software/proprietary/policy/store/JpaPolicyStore.java

@@ -17,6 +17,7 @@ import stirling.software.proprietary.policy.model.Policy;
 import stirling.software.proprietary.policy.model.PolicyBinding;
 import stirling.software.proprietary.policy.source.EditorSource;
 
+import tools.jackson.databind.DeserializationFeature;
 import tools.jackson.databind.JsonNode;
 import tools.jackson.databind.ObjectMapper;
 import tools.jackson.databind.node.ArrayNode;
@@ -47,6 +48,8 @@ public class JpaPolicyStore implements PolicyStore {
                         policy.name(),
                         policy.owner(),
                         policy.enabled(),
+                        policy.required(),
+                        policy.icon(),
                         policy.inputs(),
                         policy.steps(),
                         policy.output(),
@@ -155,7 +158,14 @@ public class JpaPolicyStore implements PolicyStore {
             JsonNode node =
                     liftEditorConfig(
                             upgradeLegacyShape(objectMapper.readTree(entity.getPolicyJson())));
-            return Optional.of(objectMapper.treeToValue(node, Policy.class));
+            // A blob written by an older version won't carry fields added since (e.g. required,
+            // icon). Default absent primitives rather than rejecting the whole policy, so upgrades
+            // don't drop existing pipelines.
+            return Optional.of(
+                    objectMapper
+                            .readerFor(Policy.class)
+                            .without(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES)
+                            .readValue(node));
         } catch (Exception e) {
             log.error(
                     "Skipping unreadable policy id={} name={}: stored JSON could not be parsed"

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

@@ -185,6 +185,7 @@ public class AiWorkflowService {
             initialRequest.setConversationHistory(
                     new ArrayList<>(request.getConversationHistory()));
             initialRequest.setEnabledEndpoints(endpointResolver.getEnabledEndpointUrls());
+            initialRequest.setLocale(request.getLocale());
             listener.onProgress(AiWorkflowProgressEvent.of(AiWorkflowPhase.ANALYZING));
 
             WorkflowState state = new WorkflowState.Pending(initialRequest);
@@ -287,6 +288,7 @@ public class AiWorkflowService {
             nextRequest.setArtifacts(pdfContentExtractor.buildArtifacts(contentResults));
             nextRequest.setResumeWith(response.getResumeWith());
             nextRequest.setEnabledEndpoints(request.getEnabledEndpoints());
+            nextRequest.setLocale(request.getLocale());
             return new WorkflowState.Pending(nextRequest);
         } finally {
             for (LoadedFile lf : loadedFiles) {
@@ -338,6 +340,7 @@ public class AiWorkflowService {
         nextRequest.setFiles(request.getFiles());
         nextRequest.setConversationHistory(request.getConversationHistory());
         nextRequest.setResumeWith(response.getResumeWith());
+        nextRequest.setLocale(request.getLocale());
         return new WorkflowState.Pending(nextRequest);
     }
 
@@ -530,6 +533,7 @@ public class AiWorkflowService {
                                 new PdfContentExtractor.ToolReportArtifact(
                                         result.reportTool(), result.report()));
                 resumeRequest.setResumeWith(resumeWith);
+                resumeRequest.setLocale(previousRequest.getLocale());
                 return new WorkflowState.Pending(resumeRequest);
             }
 
@@ -802,5 +806,6 @@ public class AiWorkflowService {
         private List<WorkflowArtifact> artifacts = new ArrayList<>();
         private String resumeWith;
         private List<String> enabledEndpoints = new ArrayList<>();
+        private String locale;
     }
 }

app/proprietary/src/test/java/stirling/software/proprietary/policy/overview/PolicyOverviewServiceTest.java

@@ -29,11 +29,11 @@ import stirling.software.proprietary.policy.store.InProcessPolicyStore;
 import stirling.software.proprietary.policy.store.PolicyStore;
 
 /**
- * Tests for {@link PolicyOverviewService}: every Pipelines-page policy appears once with its
- * sources resolved to names, its steps and trigger/output summarised, and the KPI strip counting
- * active vs paused. Frontend/catalogue policies (owned by the Policies page) are excluded, while a
- * pipeline that uses a folder-watch trigger stays. Login is disabled so the team guards pass
- * everything through.
+ * Tests for {@link PolicyOverviewService}: every policy the caller's team owns appears once with
+ * its sources resolved to names, its steps and trigger/output summarised, and the KPI strip
+ * counting active vs paused. Since Policies were merged into Pipelines, the suggested ("catalogue")
+ * policies are listed alongside hand-built pipelines - nothing is filtered. Login is disabled so
+ * the team guards pass everything through.
  */
 class PolicyOverviewServiceTest {
 
@@ -99,9 +99,9 @@ class PolicyOverviewServiceTest {
     }
 
     @Test
-    void excludesCataloguePoliciesButKeepsFolderWatchPipelines() {
+    void listsEveryPolicyIncludingSuggestedOnes() {
         Source inbox = source("Inbox", "/inbox");
-        // A hand-built pipeline: shows.
+        // A hand-built pipeline.
         policyStore.save(
                 new Policy(
                         null,
@@ -111,7 +111,7 @@ class PolicyOverviewServiceTest {
                         List.of(),
                         List.of(new PipelineStep("/api/v1/misc/compress-pdf", Map.of())),
                         OutputSpec.inline()));
-        // A folder-watch pipeline is still a pipeline: shows.
+        // A folder-watch pipeline.
         policyStore.save(
                 new Policy(
                         null,
@@ -123,7 +123,7 @@ class PolicyOverviewServiceTest {
                                         inbox.id(), new TriggerConfig("folder-watch", Map.of()))),
                         List.of(new PipelineStep("/api/v1/misc/compress-pdf", Map.of())),
                         OutputSpec.inline()));
-        // A frontend/catalogue policy (categoryId in output options): hidden.
+        // A suggested ("catalogue") policy (categoryId in output options): now listed too.
         policyStore.save(
                 new Policy(
                         null,
@@ -137,10 +137,68 @@ class PolicyOverviewServiceTest {
         PoliciesOverviewResponse response = service.overview();
 
         assertEquals(
-                List.of("Compress pipeline", "Inbox watcher"),
+                List.of("Classification Policy", "Compress pipeline", "Inbox watcher"),
                 response.pipelines().stream().map(PolicyView::name).toList());
-        // KPIs count both visible pipelines, not the hidden catalogue policy.
-        assertEquals(List.of(2L, 2L, 0L), response.kpis().stream().map(PolicyKpi::value).toList());
+        // KPIs count all three.
+        assertEquals(List.of(3L, 3L, 0L), response.kpis().stream().map(PolicyKpi::value).toList());
+    }
+
+    @Test
+    void requiredFlagSurfacesInTheView() {
+        policyStore.save(
+                new Policy(
+                        null,
+                        "Mandatory redaction",
+                        "owner",
+                        true,
+                        true,
+                        "",
+                        List.of(),
+                        List.of(new PipelineStep("/api/v1/security/auto-redact", Map.of())),
+                        OutputSpec.inline(),
+                        List.of(),
+                        null,
+                        EditorConfig.disabled()));
+
+        PolicyView view = find(service.overview(), "Mandatory redaction");
+        assertTrue(view.required());
+    }
+
+    @Test
+    void iconIsExplicitOtherwiseFallsBackToCategory() {
+        // The policy's first-class icon wins.
+        policyStore.save(
+                new Policy(
+                        null,
+                        "Custom with icon",
+                        "owner",
+                        true,
+                        false,
+                        "shield",
+                        List.of(),
+                        List.of(new PipelineStep("/api/v1/misc/compress-pdf", Map.of())),
+                        OutputSpec.inline(),
+                        List.of(),
+                        null,
+                        EditorConfig.disabled()));
+        // No explicit icon: a template-derived policy falls back to its categoryId marker.
+        policyStore.save(
+                new Policy(
+                        null,
+                        "Template derived",
+                        "owner",
+                        true,
+                        false,
+                        "",
+                        List.of(),
+                        List.of(new PipelineStep("/api/v1/security/auto-redact", Map.of())),
+                        new OutputSpec("inline", Map.of("categoryId", "security")),
+                        List.of(),
+                        null,
+                        EditorConfig.disabled()));
+
+        assertEquals("shield", find(service.overview(), "Custom with icon").icon());
+        assertEquals("security", find(service.overview(), "Template derived").icon());
     }
 
     @Test

app/saas/src/main/java/stirling/software/saas/payg/api/PaygWalletController.java

@@ -132,10 +132,7 @@ public class PaygWalletController {
                 Objects.requireNonNull(prepaidBundleService, "prepaidBundleService");
     }
 
-    // ---------------------------------------------------------------------------------------
-    // GET /wallet — the single FE fetch
-    // ---------------------------------------------------------------------------------------
-
+    /** The single wallet fetch the frontend makes; every figure on the Plan page comes from it. */
     @GetMapping("/wallet")
     @PreAuthorize("isAuthenticated()")
     @Transactional(readOnly = true)
@@ -175,9 +172,8 @@ public class PaygWalletController {
                         : null;
 
         // Per-state by construction (see EntitlementService.computeSnapshot): free team → spend is
-        // lifetime free used, cap is the grant size; subscribed → spend is this month's net
-        // billable
-        // docs, cap is the monthly paid-doc ceiling (null = uncapped).
+        // this period's free used, cap is the period grant size; subscribed → spend is this
+        // period's net billable docs, cap is the monthly paid-doc ceiling (null = uncapped).
         int spend = clampToInt(snap.periodSpendUnits());
         Integer limit = snap.periodCapUnits() != null ? clampToInt(snap.periodCapUnits()) : null;
 
@@ -328,10 +324,7 @@ public class PaygWalletController {
         };
     }
 
-    // ---------------------------------------------------------------------------------------
-    // PATCH /cap — leader-only, cap is application-layer, no Stripe call
-    // ---------------------------------------------------------------------------------------
-
+    /** Leader-only. The cap is enforced in the application layer; Stripe is never called. */
     @PatchMapping("/cap")
     @PreAuthorize("isAuthenticated()")
     @Transactional
@@ -395,10 +388,6 @@ public class PaygWalletController {
     /** Request body for {@link #updateCap}. */
     public record UpdateCapRequest(@Min(0) int capUsd, boolean noCap) {}
 
-    // ---------------------------------------------------------------------------------------
-    // POST /wallet/refresh — drop the caller's cached snapshot so the next read is fresh
-    // ---------------------------------------------------------------------------------------
-
     /**
      * Drops the caller's team snapshot + billing cache so the next {@code GET /wallet} reflects a
      * billing state that just changed out-of-band. The subscription flip is written by a Postgres
@@ -421,10 +410,6 @@ public class PaygWalletController {
         return ResponseEntity.noContent().build();
     }
 
-    // ---------------------------------------------------------------------------------------
-    // Helpers
-    // ---------------------------------------------------------------------------------------
-
     private Optional<TeamMembership> primaryMembership(Long userId) {
         List<TeamMembership> rows = memberRepo.findPrimaryMembership(userId);
         return rows.isEmpty() ? Optional.empty() : Optional.of(rows.getFirst());

app/saas/src/main/java/stirling/software/saas/payg/api/WalletSnapshotResponse.java

@@ -9,7 +9,7 @@ import java.util.List;
  * breakdowns, recent activity) used by the PAYG Plan page.
  *
  * <p>Every number is real: the billing window is the Stripe subscription's current period (via Sync
- * Engine) for subscribed teams, the one-time free grant size comes from {@code
+ * Engine) for subscribed teams, the per-period free grant size comes from {@code
  * pricing_policy.free_tier_units} (live balance from {@code
  * payg_team_extensions.free_units_remaining}), and the per-document rate comes from the
  * subscription's Stripe Price. Fields that can't be resolved are {@code null} and the FE renders
@@ -26,15 +26,15 @@ import java.util.List;
  *     subscription period when subscribed, the calendar month otherwise.
  * @param billingPeriodEnd exclusive ISO date (yyyy-MM-dd) for the current cycle.
  * @param billableUsed alias of {@code spendUnitsThisPeriod} kept for clarity in the FE. For a free
- *     team this is the lifetime free documents used so far ({@code freeAllowance − freeRemaining});
- *     for a subscribed team it's this month's net billable documents.
- * @param billableLimit the team's document ceiling for the matching window: the one-time free grant
- *     ({@code freeAllowance}) for free teams; {@code floor(cap / perDocRate)} paid docs/month for
- *     capped subscribed teams; {@code null} when subscribed with no cap (uncapped).
- * @param freeAllowance the team's one-time free document grant size (the "N" in "X of N free").
- *     Never resets; survives subscribing. Applies to billable categories only.
- * @param freeRemaining one-time free documents still available to the team ({@code
- *     payg_team_extensions.free_units_remaining}). 0 = grant exhausted.
+ *     team this is the free documents used so far this period ({@code freeAllowance −
+ *     freeRemaining}); for a subscribed team it's this period's net billable documents.
+ * @param billableLimit the team's document ceiling for the matching window: this period's free
+ *     grant ({@code freeAllowance}) for free teams; {@code floor(cap / perDocRate)} paid docs/month
+ *     for capped subscribed teams; {@code null} when subscribed with no cap (uncapped).
+ * @param freeAllowance the team's free document grant size per period (the "N" in "X of N free").
+ *     Resets each period. Applies to billable categories only.
+ * @param freeRemaining free documents still available to the team this period ({@code
+ *     payg_team_extensions.free_units_remaining}). 0 = this period's grant is exhausted.
  * @param pricePerDocMinor paid per-document rate in minor units of {@code currency} (may be
  *     fractional — Stripe supports sub-cent rates); {@code null} when the rate can't be resolved.
  * @param currency lower-case ISO 4217 currency of the subscription's Stripe Price; {@code null}

app/saas/src/main/java/stirling/software/saas/payg/billing/TeamBillingContext.java

@@ -4,28 +4,20 @@ import java.math.BigDecimal;
 import java.time.LocalDateTime;
 
 /**
- * One team's billing facts, composed by {@link TeamBillingService}. Two independent meters live
- * here and must not be conflated:
- *
- * <ul>
- *   <li>the <b>one-time lifetime free grant</b> ({@link #freeGrantUnits} total, {@link
- *       #freeRemainingUnits} left) — gates an un-subscribed team and decides the free-vs-paid split
- *       of every job; never resets, survives subscribing;
- *   <li>the <b>monthly billing window</b> ({@link #periodStart}/{@link #periodEnd}) and the
- *       optional monthly spending cap ({@link #monthlyCapDocUnits}) — govern the subscribed invoice
- *       + cap only.
- * </ul>
+ * One team's billing facts, composed by {@link TeamBillingService}. The free grant and the spending
+ * cap are separate pools measured over one window.
  *
  * @param subscribed team has a live PAYG subscription — i.e. {@code payg_subscription_id} is set.
  *     Cleared by {@code payg_unlink_subscription} on cancellation, so a cancelled team reads false.
  * @param subscriptionId {@code payg_team_extensions.payg_subscription_id}; null when free
- * @param periodStart inclusive start of the monthly billing window — the Stripe subscription's
- *     current period when subscribed, calendar month otherwise
- * @param periodEnd exclusive end of the monthly billing window
- * @param freeGrantUnits the team's one-time free grant size (policy {@code free_tier_units}); the
- *     denominator for "used X of N free". Never resets.
- * @param freeRemainingUnits one-time free documents still available ({@code
- *     payg_team_extensions.free_units_remaining}). 0 = grant exhausted.
+ * @param periodStart inclusive start of the billing window — the Stripe subscription's current
+ *     period when subscribed, calendar month otherwise. Also the period the free grant resets on.
+ * @param periodEnd exclusive end of the billing window
+ * @param freeGrantUnits the team's free grant size per period (policy {@code free_tier_units}); the
+ *     denominator for "used X of N free"
+ * @param freeRemainingUnits free documents still available in this period ({@code
+ *     payg_team_extensions.free_units_remaining}, via {@code
+ *     TeamBillingService.remainingForPeriod}). 0 = exhausted.
  * @param perDocMinor paid per-document rate in minor units of {@link #currency()}; null when the
  *     rate can't be resolved (free team, price row unsynced) — display "unknown", never substitute
  * @param currency lower-case ISO 4217 of the subscription's Price; null when unknown

app/saas/src/main/java/stirling/software/saas/payg/billing/TeamBillingService.java

@@ -30,17 +30,8 @@ import stirling.software.saas.payg.wallet.WalletPolicy;
  * entitlement hot path and the wallet endpoint read from here, so what the customer sees is what
  * the guard enforces.
  *
- * <p>Two independent meters (design 2026-06-11 — the free allowance is a one-time lifetime grant):
- *
- * <ul>
- *   <li><b>Free grant</b> — one-time, per team. Size from {@code pricing_policy.free_tier_units};
- *       live balance from the {@code payg_team_extensions.free_units_remaining} counter (maintained
- *       by the charge pipeline). Never resets, survives subscribing. Gates un-subscribed teams and
- *       drives the free-vs-paid split.
- *   <li><b>Monthly window + cap</b> — the Stripe subscription period (calendar month otherwise) and
- *       the optional money cap. Govern the subscribed invoice + spending cap only. The per-document
- *       rate is the synced {@code stripe.prices.unit_amount} (PAYG prices are plain per-unit).
- * </ul>
+ * <p>The free grant and the spending cap are separate pools measured over one window: the Stripe
+ * subscription period when subscribed, the calendar month otherwise.
  *
  * <p>Cached per team for {@value #CACHE_TTL_SECONDS}s. {@code EntitlementService.invalidate}
  * cascades into {@link #invalidate(Long)} so both caches drop together on cap edits / webhooks.
@@ -133,12 +124,6 @@ public class TeamBillingService {
         // bug this guards against.
         boolean subscribed = subscriptionId != null;
 
-        long freeGrant = resolveGrant(teamId);
-        long freeRemaining =
-                extOpt.map(PaygTeamExtensions::getFreeUnitsRemaining)
-                        .map(Long::longValue)
-                        .orElse(0L);
-
         Optional<SubscriptionBilling> billing =
                 subscriptionId != null
                         ? subscriptionDao.findBilling(subscriptionId)
@@ -148,6 +133,19 @@ public class TeamBillingService {
                 billing.map(b -> new LocalDateTime[] {b.periodStart(), b.periodEnd()})
                         .orElseGet(TeamBillingService::calendarMonthWindow);
 
+        long freeGrant = resolveGrant(teamId);
+        // The reset is persisted lazily by the charge pipeline, so the raw counter still reads as
+        // last period's for a team that has run nothing since the boundary.
+        long freeRemaining =
+                extOpt.map(
+                                ext ->
+                                        remainingForPeriod(
+                                                ext.getFreeUnitsPeriodStart(),
+                                                ext.getFreeUnitsRemaining(),
+                                                freeGrant,
+                                                window[0]))
+                        .orElse(0L);
+
         BigDecimal perDocMinor = billing.map(SubscriptionBilling::perDocMinor).orElse(null);
         String currency = billing.map(SubscriptionBilling::currency).orElse(null);
 
@@ -184,7 +182,6 @@ public class TeamBillingService {
                 monthlyCapDocUnits);
     }
 
-    /** The policy grant size — the "N" denominator for display; the counter is the live balance. */
     private long resolveGrant(Long teamId) {
         try {
             PricingPolicy policy = pricingPolicyService.getEffectivePolicy(teamId);
@@ -198,8 +195,8 @@ public class TeamBillingService {
 
     /**
      * The subscribed monthly paid-document ceiling; {@code null} = uncapped or not subscribed. The
-     * one-time free grant is NOT added here — it's a separate lifetime pool consumed at charge
-     * time. The cap purely limits how many paid documents the team will fund per billing period.
+     * free grant is NOT added here — it's a separate per-period pool consumed at charge time, ahead
+     * of the meter. The cap purely limits how many paid documents the team will fund per period.
      *
      * <ul>
      *   <li>not subscribed → null (the free grant, not a money cap, is what bounds them);
@@ -250,7 +247,7 @@ public class TeamBillingService {
     /**
      * Documents a hypothetical monthly money cap would buy: {@code floor(capMinor / rate)}. Used by
      * the cap editor's live preview and the {@code PATCH /cap} derived write. The free grant is NOT
-     * added — it's a separate one-time pool. Empty when the rate is unknown.
+     * added — it's a separate per-period pool. Empty when the rate is unknown.
      */
     public Optional<Long> docCapForMoney(TeamBillingContext ctx, long capMinor) {
         if (ctx.perDocMinor() == null || ctx.perDocMinor().signum() <= 0) {
@@ -279,6 +276,28 @@ public class TeamBillingService {
                 .orElse(null);
     }
 
+    /**
+     * The team's free balance for the period starting at {@code currentPeriodStart}: a full grant
+     * when the counter is stale, the counter otherwise. Shared with the decrement in {@code
+     * JobChargeService} so displayed and enforced balances cannot diverge.
+     */
+    public static long remainingForPeriod(
+            LocalDateTime stampedPeriodStart,
+            Long storedRemaining,
+            long grant,
+            LocalDateTime currentPeriodStart) {
+        if (isStale(stampedPeriodStart, currentPeriodStart)) {
+            return Math.max(0L, grant);
+        }
+        return storedRemaining == null ? 0L : Math.max(0L, storedRemaining);
+    }
+
+    public static boolean isStale(
+            LocalDateTime stampedPeriodStart, LocalDateTime currentPeriodStart) {
+        return currentPeriodStart != null
+                && (stampedPeriodStart == null || stampedPeriodStart.isBefore(currentPeriodStart));
+    }
+
     /**
      * Inclusive-start / exclusive-end window for the calendar month — the monthly billing window
      * used when there's no Stripe subscription period to anchor on.

app/saas/src/main/java/stirling/software/saas/payg/charge/JobChargeService.java

@@ -17,6 +17,8 @@ import org.springframework.web.multipart.MultipartFile;
 
 import lombok.extern.slf4j.Slf4j;
 
+import stirling.software.saas.payg.billing.TeamBillingContext;
+import stirling.software.saas.payg.billing.TeamBillingService;
 import stirling.software.saas.payg.bundle.PrepaidBundleService;
 import stirling.software.saas.payg.docs.DocumentClassifier;
 import stirling.software.saas.payg.docs.DocumentMetrics;
@@ -70,6 +72,7 @@ public class JobChargeService {
     private final PaygMeterReportingService meterReportingService;
     private final WalletLedgerRepository ledgerRepository;
     private final PrepaidBundleService prepaidBundleService;
+    private final TeamBillingService teamBillingService;
 
     public JobChargeService(
             JobService jobService,
@@ -80,7 +83,8 @@ public class JobChargeService {
             PaygTeamExtensionsRepository teamExtensionsRepository,
             PaygMeterReportingService meterReportingService,
             WalletLedgerRepository ledgerRepository,
-            PrepaidBundleService prepaidBundleService) {
+            PrepaidBundleService prepaidBundleService,
+            TeamBillingService teamBillingService) {
         this.jobService = Objects.requireNonNull(jobService, "jobService");
         this.policyService = Objects.requireNonNull(policyService, "policyService");
         this.classifier = Objects.requireNonNull(classifier, "classifier");
@@ -93,6 +97,7 @@ public class JobChargeService {
         this.ledgerRepository = Objects.requireNonNull(ledgerRepository, "ledgerRepository");
         this.prepaidBundleService =
                 Objects.requireNonNull(prepaidBundleService, "prepaidBundleService");
+        this.teamBillingService = Objects.requireNonNull(teamBillingService, "teamBillingService");
     }
 
     /**
@@ -208,13 +213,13 @@ public class JobChargeService {
     }
 
     /**
-     * Draw this job's free portion from the team's one-time lifetime grant, atomically, and return
-     * the units taken (0..{@code units}); the remainder is the paid portion that will be metered to
-     * Stripe. Runs inside {@code openProcess}'s transaction with a pessimistic row lock so
-     * concurrent same-team charges split the grant exactly — no two jobs can both claim the last
-     * free unit. The grant is a soft floor: it never goes below 0, and the single job that crosses
-     * the boundary takes whatever's left (its remaining units bill). Skipped for non-billable /
-     * team-less calls (BYPASSED never reaches openProcess; guarded defensively).
+     * Units of {@code units} drawn from the team's grant for the current period; the remainder is
+     * metered to Stripe. The grant is a soft floor, so the job crossing the boundary takes what is
+     * left and bills the rest.
+     *
+     * <p>Also the only writer of the period reset. Both happen under {@code openProcess}'s row
+     * lock, against the balance on the locked row rather than the cached context, so concurrent
+     * same-team charges cannot both claim the last free unit.
      */
     private int consumeFreeGrant(ChargeContext ctx, int units) {
         BillingCategory category = ctx.billingCategory();
@@ -227,15 +232,51 @@ public class JobChargeService {
             return 0;
         }
         PaygTeamExtensions ext = extOpt.get();
-        long remaining = ext.getFreeUnitsRemaining() == null ? 0L : ext.getFreeUnitsRemaining();
+        TeamBillingContext billing = teamBillingService.forTeam(ctx.ownerTeamId());
+        LocalDateTime periodStart = billing.periodStart();
+        boolean periodRolled =
+                TeamBillingService.isStale(ext.getFreeUnitsPeriodStart(), periodStart);
+        long remaining =
+                TeamBillingService.remainingForPeriod(
+                        ext.getFreeUnitsPeriodStart(),
+                        ext.getFreeUnitsRemaining(),
+                        billing.freeGrantUnits(),
+                        periodStart);
         int freeUsed = (int) Math.min(units, Math.max(0L, remaining));
-        if (freeUsed > 0) {
+        if (periodRolled || freeUsed > 0) {
+            // A roll-over writes even when nothing is drawn, so the stamp stops reading as stale.
             ext.setFreeUnitsRemaining(remaining - freeUsed);
+            ext.setFreeUnitsPeriodStart(periodStart);
             teamExtensionsRepository.save(ext);
         }
         return freeUsed;
     }
 
+    /**
+     * Return {@code units} to the team's free grant, capped at one period's grant. The cap only
+     * bites when a refund lands after its charge's period ended, where the balance has already
+     * reset and adding the old units would over-credit the team. Locks rather than incrementing
+     * blindly because the cap applies against the balance as it stands.
+     */
+    private void restoreFreeGrant(Long teamId, int units) {
+        Optional<PaygTeamExtensions> extOpt = teamExtensionsRepository.findByIdForUpdate(teamId);
+        if (extOpt.isEmpty()) {
+            return;
+        }
+        PaygTeamExtensions ext = extOpt.get();
+        TeamBillingContext billing = teamBillingService.forTeam(teamId);
+        long grant = billing.freeGrantUnits();
+        long remaining =
+                TeamBillingService.remainingForPeriod(
+                        ext.getFreeUnitsPeriodStart(),
+                        ext.getFreeUnitsRemaining(),
+                        grant,
+                        billing.periodStart());
+        ext.setFreeUnitsRemaining(Math.min(grant, remaining + Math.max(0, units)));
+        ext.setFreeUnitsPeriodStart(billing.periodStart());
+        teamExtensionsRepository.save(ext);
+    }
+
     /**
      * Draw this job's prepaid portion from the team's bundles — the tier after the free grant and
      * before the meter — returning the units taken (0..{@code units}). Same guard as {@link
@@ -405,13 +446,11 @@ public class JobChargeService {
                     refund.setPolicyId(row.getPolicyId());
                     refund.setBillingCategory(category);
                     ledgerRepository.save(refund);
-                    // Hand back the free units this job consumed (first-step failures are
-                    // pre-meter, so nothing was billed to Stripe — only the grant moved). Exactly
-                    // what was taken at charge time, so the counter can't drift above the grant.
+                    // First-step failures are pre-meter: nothing was billed, only the grant moved.
                     int freeConsumed =
                             row.getFreeUnitsConsumed() == null ? 0 : row.getFreeUnitsConsumed();
                     if (freeConsumed > 0 && row.getTeamId() != null) {
-                        teamExtensionsRepository.restoreFreeUnits(row.getTeamId(), freeConsumed);
+                        restoreFreeGrant(row.getTeamId(), freeConsumed);
                     }
                     // Return the prepaid units this job drew to the team's pools (best-effort — see
                     // PrepaidBundleService.restore).
@@ -553,9 +592,7 @@ public class JobChargeService {
             return;
         }
 
-        // Paid portion = units beyond the team's one-time free grant, fixed at charge time. The
-        // free grant is app-side only (Stripe's Prices are plain per-unit, no free tier), so the
-        // free units were already withheld when this row's free_units_consumed was set.
+        // Free units are withheld app-side at charge time; Stripe's Prices carry no free tier.
         int freeConsumed = row.getFreeUnitsConsumed() == null ? 0 : row.getFreeUnitsConsumed();
         int bundleConsumed =
                 row.getBundleUnitsConsumed() == null ? 0 : row.getBundleUnitsConsumed();

app/saas/src/main/java/stirling/software/saas/payg/entitlement/EntitlementService.java

@@ -134,8 +134,8 @@ public class EntitlementService {
 
         if (billing.subscribed()) {
             // Subscribed: gate on the monthly spending cap. Spend = this period's net billable
-            // documents (DEBIT minus REFUND so a refunded job doesn't read as spent). The one-time
-            // free grant doesn't gate a paying team — it only reduced what they were metered.
+            // documents (DEBIT minus REFUND so a refunded job doesn't read as spent). The free
+            // grant doesn't gate a paying team — it only reduced what they were metered.
             long signedNet = ledgerRepository.sumPeriodNetBillable(teamId, periodStart, periodEnd);
             long periodSpend = signedNet < 0 ? -signedNet : 0L;
             Long cap = billing.monthlyCapDocUnits();
@@ -157,14 +157,8 @@ public class EntitlementService {
             snapshotSpend = periodSpend;
             snapshotCap = cap;
         } else {
-            // Unsubscribed: gate on the one-time lifetime free grant, then on a prepaid pool. While
-            // the free grant has balance, evaluate the warn/degrade band on used-of-grant. Once the
-            // free grant is spent, a live prepaid pool keeps the team fully entitled — paid-for
-            // capacity is usable on its own merit, independent of any metered subscription (the
-            // pool
-            // is drawn in JobChargeService; only the metered remainder stays gated on the sub).
-            // Only
-            // when BOTH the free grant and prepaid are exhausted do billable categories hard-stop.
+            // A prepaid pool outranks an exhausted grant: paid-for capacity is usable on its own
+            // merit, with no subscription. Only with both gone do billable categories hard-stop.
             long grant = billing.freeGrantUnits();
             long remaining = billing.freeRemainingUnits();
             long used = Math.max(0L, grant - remaining);

app/saas/src/main/java/stirling/software/saas/payg/policy/PaygTeamExtensions.java

@@ -72,15 +72,22 @@ public class PaygTeamExtensions implements Serializable {
     private String paygSubscriptionId;
 
     /**
-     * Remaining one-time free documents for this team (the lifetime grant). Seeded from the
-     * effective pricing policy's {@code free_tier_units} when this row is created (V14 trigger,
-     * updated in V19); decremented by the charge pipeline when a billable charge is written and
-     * restored on a first-step refund. Never replenishes; survives subscribing. This counter — not
-     * the wallet ledger — is the source of truth for the grant, so old ledger rows can be pruned.
+     * Free documents left in the team's current billing period, reset to the policy's {@code
+     * free_tier_units} at each boundary (see {@link #freeUnitsPeriodStart}). This counter, not the
+     * wallet ledger, is the source of truth for the grant.
      */
     @Column(name = "free_units_remaining", nullable = false)
     private Long freeUnitsRemaining = 0L;
 
+    /**
+     * The billing period {@link #freeUnitsRemaining} was last reset for, always a {@code
+     * TeamBillingContext.periodStart}. {@code null} or older than the current period start means
+     * the counter is stale and reads as a full grant. Written only by the app, which owns the
+     * period rule.
+     */
+    @Column(name = "free_units_period_start")
+    private LocalDateTime freeUnitsPeriodStart;
+
     @CreationTimestamp
     @Column(name = "created_at", updatable = false)
     private LocalDateTime createdAt;

app/saas/src/main/java/stirling/software/saas/payg/policy/PricingPolicy.java

@@ -74,11 +74,9 @@ public class PricingPolicy implements Serializable {
     private Integer fileUnitCap = 1000;
 
     /**
-     * One-time lifetime free document grant handed to a team on creation. {@code 0} (default) means
-     * no free grant. NOT per-cycle: it never replenishes and a team keeps any unused portion after
-     * subscribing. The value is copied into {@code payg_team_extensions.free_units_remaining} when
-     * the team's sidecar row is created (V14 trigger, updated in V19); from then on the per-team
-     * counter is authoritative and this column is only the seed for new teams.
+     * Free document grant a team gets each billing period; {@code 0} (default) means none. The
+     * size, not the balance: {@code payg_team_extensions.free_units_remaining} is reset to it at
+     * each period boundary and does not carry over.
      */
     @Column(name = "free_tier_units", nullable = false)
     private Long freeTierUnits = 0L;

app/saas/src/main/java/stirling/software/saas/payg/repository/PaygTeamExtensionsRepository.java

@@ -4,7 +4,6 @@ import java.util.Optional;
 
 import org.springframework.data.jpa.repository.JpaRepository;
 import org.springframework.data.jpa.repository.Lock;
-import org.springframework.data.jpa.repository.Modifying;
 import org.springframework.data.jpa.repository.Query;
 import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
@@ -19,24 +18,10 @@ public interface PaygTeamExtensionsRepository extends JpaRepository<PaygTeamExte
     Optional<PaygTeamExtensions> findByStripeCustomerId(String stripeCustomerId);
 
     /**
-     * Pessimistic-write load of the sidecar row, used by the charge pipeline to deduct the one-time
-     * free grant atomically. The lock serialises concurrent charges <em>for the same team</em> so
-     * the per-job {@code free_units_consumed} split (and therefore the metered paid portion) is
-     * exact — two simultaneous jobs can't both believe they drew from the same remaining unit.
-     * Different teams never contend; the lock is held only for the {@code openProcess} transaction.
+     * Serialises concurrent charges for one team so the per-job {@code free_units_consumed} split
+     * is exact: without the lock two simultaneous jobs both draw the same remaining free unit.
      */
     @Lock(LockModeType.PESSIMISTIC_WRITE)
     @Query("SELECT e FROM PaygTeamExtensions e WHERE e.teamId = :teamId")
     Optional<PaygTeamExtensions> findByIdForUpdate(@Param("teamId") Long teamId);
-
-    /**
-     * Atomically returns {@code freeUnitsConsumed} to the team's grant on a refund. Increment is
-     * commutative so no lock is needed; the amount restored is exactly what the job consumed, so it
-     * can never exceed the original grant.
-     */
-    @Modifying
-    @Query(
-            "UPDATE PaygTeamExtensions e SET e.freeUnitsRemaining = e.freeUnitsRemaining + :units"
-                    + " WHERE e.teamId = :teamId")
-    int restoreFreeUnits(@Param("teamId") Long teamId, @Param("units") long units);
 }

app/saas/src/main/java/stirling/software/saas/payg/shadow/PaygShadowCharge.java

@@ -59,10 +59,10 @@ public class PaygShadowCharge implements Serializable {
     private Integer paygUnits;
 
     /**
-     * How many of {@link #paygUnits} were drawn from the team's one-time free grant at charge time.
-     * The paid (Stripe-metered) portion is {@code paygUnits - freeUnitsConsumed}; a refund restores
-     * this many units to {@code payg_team_extensions.free_units_remaining}. {@code 0} for pre-V19
-     * rows and for jobs that consumed no free units (team's grant already exhausted).
+     * How many of {@link #paygUnits} were drawn from the team's free grant at charge time. The paid
+     * (Stripe-metered) portion is {@code paygUnits - freeUnitsConsumed}; a refund restores this
+     * many units to {@code payg_team_extensions.free_units_remaining}. {@code 0} for pre-V19 rows
+     * and for jobs that drew no free units.
      */
     @Column(name = "free_units_consumed", nullable = false)
     private Integer freeUnitsConsumed = 0;

app/saas/src/main/java/stirling/software/saas/payg/stripe/StripeSubscriptionDao.java

@@ -24,7 +24,7 @@ import lombok.extern.slf4j.Slf4j;
  * {@code stirling_pdf} (money lives in Stripe).
  *
  * <p>PAYG prices are plain {@code per_unit} metered prices, so {@code stripe.prices.unit_amount}
- * carries the rate directly. The free grant is deliberately NOT in Stripe - it's the one-time
+ * carries the rate directly. The free grant is deliberately NOT in Stripe - it's the per-period
  * {@code pricing_policy.free_tier_units} pool, applied app-side (free units are never metered),
  * because un-subscribed teams get the same grant and have no Stripe Price at all.
  *

app/saas/src/test/java/stirling/software/saas/payg/billing/TeamBillingServiceMoreTest.java

@@ -64,6 +64,7 @@ class TeamBillingServiceMoreTest {
         e.setTeamId(TEAM_ID);
         e.setPaygSubscriptionId(subscriptionId);
         e.setFreeUnitsRemaining(freeRemaining);
+        e.setFreeUnitsPeriodStart(TeamBillingService.calendarMonthWindow()[0]);
         return e;
     }
 
@@ -360,4 +361,132 @@ class TeamBillingServiceMoreTest {
             assertThat(window[1]).isEqualTo(YearMonth.now().plusMonths(1).atDay(1).atStartOfDay());
         }
     }
+
+    @Nested
+    @DisplayName("compute: recurring free grant")
+    class RecurringFreeGrant {
+
+        private static final long GRANT = 500L;
+
+        private PaygTeamExtensions stamped(LocalDateTime stamp, long remaining) {
+            PaygTeamExtensions e = new PaygTeamExtensions();
+            e.setTeamId(TEAM_ID);
+            e.setFreeUnitsRemaining(remaining);
+            e.setFreeUnitsPeriodStart(stamp);
+            return e;
+        }
+
+        @Test
+        @DisplayName("a counter stamped with a past period reads as a fresh grant")
+        void staleStampReadsAsFreshGrant() {
+            stubGrant(GRANT);
+            // Nothing has persisted the reset yet, so the read has to show it anyway.
+            when(extensionsRepository.findById(TEAM_ID))
+                    .thenReturn(
+                            Optional.of(
+                                    stamped(
+                                            LocalDateTime.now().minusMonths(2).withDayOfMonth(1),
+                                            0L)));
+
+            TeamBillingContext ctx = service.forTeam(TEAM_ID);
+
+            assertThat(ctx.freeGrantUnits()).isEqualTo(GRANT);
+            assertThat(ctx.freeRemainingUnits()).isEqualTo(GRANT);
+        }
+
+        @Test
+        @DisplayName("a counter stamped with the current period reads as the stored balance")
+        void currentStampReadsStoredBalance() {
+            stubGrant(GRANT);
+            when(extensionsRepository.findById(TEAM_ID))
+                    .thenReturn(
+                            Optional.of(
+                                    stamped(TeamBillingService.calendarMonthWindow()[0], 120L)));
+
+            assertThat(service.forTeam(TEAM_ID).freeRemainingUnits()).isEqualTo(120L);
+        }
+
+        @Test
+        @DisplayName(
+                "an unstamped row — written before the grant recurred — reads as a fresh grant")
+        void nullStampReadsAsFreshGrant() {
+            stubGrant(GRANT);
+            when(extensionsRepository.findById(TEAM_ID)).thenReturn(Optional.of(stamped(null, 0L)));
+
+            assertThat(service.forTeam(TEAM_ID).freeRemainingUnits()).isEqualTo(GRANT);
+        }
+
+        @Test
+        @DisplayName("the grant resets on the Stripe window, not the calendar month")
+        void subscribedGrantFollowsTheStripeWindow() {
+            stubGrant(GRANT);
+            // Stamped for the calendar month, but this team's period is Stripe-anchored and starts
+            // mid-month, so the stamp belongs to the previous period and the grant resets.
+            LocalDateTime stripeStart = LocalDateTime.of(2026, 6, 10, 0, 0);
+            when(extensionsRepository.findById(TEAM_ID))
+                    .thenReturn(Optional.of(subscribedRow(LocalDateTime.of(2026, 6, 1, 0, 0))));
+            when(subscriptionDao.findBilling("sub_1"))
+                    .thenReturn(
+                            Optional.of(
+                                    new SubscriptionBilling(
+                                            stripeStart,
+                                            stripeStart.plusMonths(1),
+                                            "price_1",
+                                            "active",
+                                            "usd",
+                                            new BigDecimal("2"))));
+
+            TeamBillingContext ctx = service.forTeam(TEAM_ID);
+
+            assertThat(ctx.periodStart()).isEqualTo(stripeStart);
+            assertThat(ctx.freeRemainingUnits()).isEqualTo(GRANT);
+        }
+
+        private PaygTeamExtensions subscribedRow(LocalDateTime stamp) {
+            PaygTeamExtensions e = stamped(stamp, 0L);
+            e.setPaygSubscriptionId("sub_1");
+            return e;
+        }
+    }
+
+    @Nested
+    @DisplayName("remainingForPeriod")
+    class RemainingForPeriodRule {
+
+        private final LocalDateTime period = LocalDateTime.of(2026, 8, 1, 0, 0);
+
+        @Test
+        @DisplayName("stale stamp yields the full grant; current stamp yields the stored balance")
+        void staleVersusCurrent() {
+            assertThat(
+                            TeamBillingService.remainingForPeriod(
+                                    period.minusMonths(1), 0L, 500L, period))
+                    .isEqualTo(500L);
+            assertThat(TeamBillingService.remainingForPeriod(period, 0L, 500L, period)).isZero();
+            assertThat(TeamBillingService.remainingForPeriod(period, 42L, 500L, period))
+                    .isEqualTo(42L);
+        }
+
+        @Test
+        @DisplayName("a stamp in the future is never read as another grant")
+        void futureStampKeepsTheStoredBalance() {
+            assertThat(TeamBillingService.remainingForPeriod(period.plusDays(1), 7L, 500L, period))
+                    .isEqualTo(7L);
+        }
+
+        @Test
+        @DisplayName("null stored balance and negative values floor at zero")
+        void nullAndNegativeBalances() {
+            assertThat(TeamBillingService.remainingForPeriod(period, null, 500L, period)).isZero();
+            assertThat(TeamBillingService.remainingForPeriod(period, -5L, 500L, period)).isZero();
+            assertThat(TeamBillingService.remainingForPeriod(null, 0L, -1L, period)).isZero();
+        }
+
+        @Test
+        @DisplayName("an unknown current period leaves the counter alone")
+        void nullCurrentPeriod() {
+            assertThat(TeamBillingService.isStale(null, null)).isFalse();
+            assertThat(TeamBillingService.remainingForPeriod(null, 3L, 500L, null)).isEqualTo(3L);
+        }
+    }
 }

app/saas/src/test/java/stirling/software/saas/payg/billing/TeamBillingServiceTest.java

@@ -58,12 +58,14 @@ class TeamBillingServiceTest {
         when(pricingPolicyService.getEffectivePolicy(TEAM_ID)).thenReturn(policy);
     }
 
+    /** Stamped with the current period, so {@code freeRemaining} reads as the live balance. */
     private PaygTeamExtensions ext(String subscriptionId, String customerId, long freeRemaining) {
         PaygTeamExtensions ext = new PaygTeamExtensions();
         ext.setTeamId(TEAM_ID);
         ext.setPaygSubscriptionId(subscriptionId);
         ext.setStripeCustomerId(customerId);
         ext.setFreeUnitsRemaining(freeRemaining);
+        ext.setFreeUnitsPeriodStart(TeamBillingService.calendarMonthWindow()[0]);
         return ext;
     }
 

app/saas/src/test/java/stirling/software/saas/payg/charge/JobChargeServiceTest.java

@@ -31,6 +31,8 @@ import org.springframework.transaction.support.TransactionSynchronization;
 import org.springframework.transaction.support.TransactionSynchronizationManager;
 import org.springframework.web.multipart.MultipartFile;
 
+import stirling.software.saas.payg.billing.TeamBillingContext;
+import stirling.software.saas.payg.billing.TeamBillingService;
 import stirling.software.saas.payg.bundle.PrepaidBundleService;
 import stirling.software.saas.payg.docs.DocumentClassifier;
 import stirling.software.saas.payg.docs.DocumentMetrics;
@@ -72,8 +74,13 @@ class JobChargeServiceTest {
     private PaygMeterReportingService meterReporter;
     private WalletLedgerRepository ledgerRepo;
     private PrepaidBundleService prepaidBundleService;
+    private TeamBillingService teamBillingService;
     private JobChargeService service;
 
+    private static final LocalDateTime PERIOD_START = LocalDateTime.of(2026, 8, 1, 0, 0);
+
+    private static final long GRANT = 500L;
+
     @BeforeEach
     void setUp() {
         jobService = Mockito.mock(JobService.class);
@@ -90,6 +97,8 @@ class JobChargeServiceTest {
         // findByIdForUpdate defaults to Optional.empty() (Mockito) → no free grant consumed unless
         // a test stubs the sidecar row. The free split is decided at openProcess time now, not at
         // close, so the meter tests just set free_units_consumed on the shadow row directly.
+        teamBillingService = Mockito.mock(TeamBillingService.class);
+        when(teamBillingService.forTeam(Mockito.anyLong())).thenReturn(billingContext(GRANT));
         service =
                 new JobChargeService(
                         jobService,
@@ -100,7 +109,22 @@ class JobChargeServiceTest {
                         teamExtRepo,
                         meterReporter,
                         ledgerRepo,
-                        prepaidBundleService);
+                        prepaidBundleService,
+                        teamBillingService);
+    }
+
+    private static TeamBillingContext billingContext(long grant) {
+        return new TeamBillingContext(
+                false,
+                null,
+                PERIOD_START,
+                PERIOD_START.plusMonths(1),
+                grant,
+                grant,
+                null,
+                null,
+                null,
+                null);
     }
 
     @AfterEach
@@ -365,6 +389,7 @@ class JobChargeServiceTest {
         PaygTeamExtensions ext = new PaygTeamExtensions();
         ext.setTeamId(100L);
         ext.setFreeUnitsRemaining(10L);
+        ext.setFreeUnitsPeriodStart(PERIOD_START);
         when(teamExtRepo.findByIdForUpdate(100L)).thenReturn(Optional.of(ext));
 
         service.openProcess(
@@ -381,6 +406,96 @@ class JobChargeServiceTest {
         verify(teamExtRepo).save(ext);
     }
 
+    @Test
+    void openProcess_firstChargeOfNewPeriod_resetsGrantAndRestamps(@TempDir Path tmp)
+            throws IOException {
+        // Grant exhausted last period, nothing run since. This charge persists the reset: counter
+        // back to the full grant, drawn from, and re-stamped so the next charge reads the balance.
+        PricingPolicy policy = stubPolicy(1, Map.of(JobSource.WEB, 10));
+        when(policyService.getEffectivePolicy(100L)).thenReturn(policy);
+        ProcessingJob newJob = openJob(UUID.randomUUID());
+        when(jobService.joinOrOpen(any(JobContext.class), anyList()))
+                .thenReturn(new JoinOrOpenResult(newJob, JoinOrOpenResult.Disposition.OPENED));
+        when(classifier.classify(any(MultipartFile.class), any(Path.class), eq(policy)))
+                .thenReturn(new DocumentMetrics(50, 1024L, "application/pdf", 4));
+
+        PaygTeamExtensions ext = new PaygTeamExtensions();
+        ext.setTeamId(100L);
+        ext.setFreeUnitsRemaining(0L);
+        ext.setFreeUnitsPeriodStart(PERIOD_START.minusMonths(1));
+        when(teamExtRepo.findByIdForUpdate(100L)).thenReturn(Optional.of(ext));
+
+        service.openProcess(
+                new ChargeContext(
+                        42L, 100L, JobSource.WEB, ProcessType.SINGLE_TOOL, BillingCategory.API),
+                List.of(jobInput(tmp, "in.pdf", "application/pdf")));
+
+        ArgumentCaptor<PaygShadowCharge> captor = ArgumentCaptor.forClass(PaygShadowCharge.class);
+        verify(shadowRepo).save(captor.capture());
+        assertThat(captor.getValue().getFreeUnitsConsumed()).isEqualTo(4);
+        assertThat(ext.getFreeUnitsRemaining()).isEqualTo(GRANT - 4);
+        assertThat(ext.getFreeUnitsPeriodStart()).isEqualTo(PERIOD_START);
+        verify(teamExtRepo).save(ext);
+    }
+
+    @Test
+    void openProcess_unstampedRow_resetsToGrantAndStamps(@TempDir Path tmp) throws IOException {
+        // An unstamped row must read as owed a reset, not as an exhausted pool.
+        PricingPolicy policy = stubPolicy(1, Map.of(JobSource.WEB, 10));
+        when(policyService.getEffectivePolicy(100L)).thenReturn(policy);
+        ProcessingJob newJob = openJob(UUID.randomUUID());
+        when(jobService.joinOrOpen(any(JobContext.class), anyList()))
+                .thenReturn(new JoinOrOpenResult(newJob, JoinOrOpenResult.Disposition.OPENED));
+        when(classifier.classify(any(MultipartFile.class), any(Path.class), eq(policy)))
+                .thenReturn(new DocumentMetrics(50, 1024L, "application/pdf", 1));
+
+        PaygTeamExtensions ext = new PaygTeamExtensions();
+        ext.setTeamId(100L);
+        ext.setFreeUnitsRemaining(0L);
+        when(teamExtRepo.findByIdForUpdate(100L)).thenReturn(Optional.of(ext));
+
+        service.openProcess(
+                new ChargeContext(
+                        42L, 100L, JobSource.WEB, ProcessType.SINGLE_TOOL, BillingCategory.API),
+                List.of(jobInput(tmp, "in.pdf", "application/pdf")));
+
+        ArgumentCaptor<PaygShadowCharge> captor = ArgumentCaptor.forClass(PaygShadowCharge.class);
+        verify(shadowRepo).save(captor.capture());
+        assertThat(captor.getValue().getFreeUnitsConsumed()).isEqualTo(1);
+        assertThat(ext.getFreeUnitsRemaining()).isEqualTo(GRANT - 1);
+        assertThat(ext.getFreeUnitsPeriodStart()).isEqualTo(PERIOD_START);
+    }
+
+    @Test
+    void openProcess_zeroGrantRollover_stampsWithoutDrawing(@TempDir Path tmp) throws IOException {
+        // A zero grant still advances the stamp, or every later charge re-evaluates a stale row.
+        when(teamBillingService.forTeam(100L)).thenReturn(billingContext(0L));
+        PricingPolicy policy = stubPolicy(1, Map.of(JobSource.WEB, 10));
+        when(policyService.getEffectivePolicy(100L)).thenReturn(policy);
+        ProcessingJob newJob = openJob(UUID.randomUUID());
+        when(jobService.joinOrOpen(any(JobContext.class), anyList()))
+                .thenReturn(new JoinOrOpenResult(newJob, JoinOrOpenResult.Disposition.OPENED));
+        when(classifier.classify(any(MultipartFile.class), any(Path.class), eq(policy)))
+                .thenReturn(new DocumentMetrics(50, 1024L, "application/pdf", 3));
+
+        PaygTeamExtensions ext = new PaygTeamExtensions();
+        ext.setTeamId(100L);
+        ext.setFreeUnitsRemaining(0L);
+        when(teamExtRepo.findByIdForUpdate(100L)).thenReturn(Optional.of(ext));
+
+        service.openProcess(
+                new ChargeContext(
+                        42L, 100L, JobSource.WEB, ProcessType.SINGLE_TOOL, BillingCategory.API),
+                List.of(jobInput(tmp, "in.pdf", "application/pdf")));
+
+        ArgumentCaptor<PaygShadowCharge> captor = ArgumentCaptor.forClass(PaygShadowCharge.class);
+        verify(shadowRepo).save(captor.capture());
+        assertThat(captor.getValue().getFreeUnitsConsumed()).isZero();
+        assertThat(ext.getFreeUnitsRemaining()).isZero();
+        assertThat(ext.getFreeUnitsPeriodStart()).isEqualTo(PERIOD_START);
+        verify(teamExtRepo).save(ext);
+    }
+
     @Test
     void openProcess_grantStraddle_drawsRemainderFreeAndBillsTheRest(@TempDir Path tmp)
             throws IOException {
@@ -396,6 +511,7 @@ class JobChargeServiceTest {
         PaygTeamExtensions ext = new PaygTeamExtensions();
         ext.setTeamId(100L);
         ext.setFreeUnitsRemaining(3L);
+        ext.setFreeUnitsPeriodStart(PERIOD_START);
         when(teamExtRepo.findByIdForUpdate(100L)).thenReturn(Optional.of(ext));
 
         service.openProcess(
@@ -426,6 +542,7 @@ class JobChargeServiceTest {
         PaygTeamExtensions ext = new PaygTeamExtensions();
         ext.setTeamId(100L);
         ext.setFreeUnitsRemaining(0L);
+        ext.setFreeUnitsPeriodStart(PERIOD_START);
         when(teamExtRepo.findByIdForUpdate(100L)).thenReturn(Optional.of(ext));
 
         service.openProcess(
@@ -544,8 +661,8 @@ class JobChargeServiceTest {
         assertThat(refund.getReferenceId()).isEqualTo(jobId.toString());
         assertThat(refund.getPolicyId()).isEqualTo(7L);
         assertThat(refund.getBillingCategory()).isEqualTo(BillingCategory.API);
-        // This row consumed no free units, so the grant counter is left alone.
-        verify(teamExtRepo, never()).restoreFreeUnits(eq(100L), Mockito.anyLong());
+        // No free units consumed, so the grant counter is never loaded.
+        verify(teamExtRepo, never()).findByIdForUpdate(100L);
     }
 
     @Test
@@ -556,10 +673,35 @@ class JobChargeServiceTest {
         PaygShadowCharge row = chargedShadowRow(jobId, 100L, 10, 3, BillingCategory.API);
         when(shadowRepo.findFirstByJobIdOrderByIdAsc(jobId)).thenReturn(Optional.of(row));
         when(jobRepo.findById(jobId)).thenReturn(Optional.of(openJob(jobId)));
+        PaygTeamExtensions ext = new PaygTeamExtensions();
+        ext.setTeamId(100L);
+        ext.setFreeUnitsRemaining(GRANT - 3);
+        ext.setFreeUnitsPeriodStart(PERIOD_START);
+        when(teamExtRepo.findByIdForUpdate(100L)).thenReturn(Optional.of(ext));
 
         service.markFirstStepFailed(jobId, "first-step-5xx:503");
 
-        verify(teamExtRepo).restoreFreeUnits(100L, 3L);
+        assertThat(ext.getFreeUnitsRemaining()).isEqualTo(GRANT);
+        verify(teamExtRepo).save(ext);
+    }
+
+    @Test
+    void markFirstStepFailed_refundAfterPeriodTurned_doesNotExceedTheGrant() {
+        // The charge's period is over and the grant already reset, so the restore is capped.
+        UUID jobId = UUID.randomUUID();
+        PaygShadowCharge row = chargedShadowRow(jobId, 100L, 10, 3, BillingCategory.API);
+        when(shadowRepo.findFirstByJobIdOrderByIdAsc(jobId)).thenReturn(Optional.of(row));
+        when(jobRepo.findById(jobId)).thenReturn(Optional.of(openJob(jobId)));
+        PaygTeamExtensions ext = new PaygTeamExtensions();
+        ext.setTeamId(100L);
+        ext.setFreeUnitsRemaining(0L);
+        ext.setFreeUnitsPeriodStart(PERIOD_START.minusMonths(1));
+        when(teamExtRepo.findByIdForUpdate(100L)).thenReturn(Optional.of(ext));
+
+        service.markFirstStepFailed(jobId, "first-step-5xx:503");
+
+        assertThat(ext.getFreeUnitsRemaining()).isEqualTo(GRANT);
+        assertThat(ext.getFreeUnitsPeriodStart()).isEqualTo(PERIOD_START);
     }
 
     @Test
@@ -886,6 +1028,7 @@ class JobChargeServiceTest {
         ext.setStripeCustomerId("cus_x");
         ext.setPaygSubscriptionId("sub_x");
         ext.setFreeUnitsRemaining(0L);
+        ext.setFreeUnitsPeriodStart(PERIOD_START);
         when(teamExtRepo.findByIdForUpdate(teamId)).thenReturn(Optional.of(ext));
         when(teamExtRepo.findById(teamId)).thenReturn(Optional.of(ext));
         when(shadowRepo.findFirstByJobIdOrderByIdAsc(jobId))
@@ -930,6 +1073,7 @@ class JobChargeServiceTest {
         PaygTeamExtensions ext = new PaygTeamExtensions();
         ext.setTeamId(teamId);
         ext.setFreeUnitsRemaining(50L);
+        ext.setFreeUnitsPeriodStart(PERIOD_START);
         when(teamExtRepo.findByIdForUpdate(teamId)).thenReturn(Optional.of(ext));
         when(teamExtRepo.findById(teamId)).thenReturn(Optional.of(ext));
         when(shadowRepo.findFirstByJobIdOrderByIdAsc(jobId))
@@ -974,6 +1118,7 @@ class JobChargeServiceTest {
         ext.setStripeCustomerId("cus_x");
         ext.setPaygSubscriptionId("sub_x");
         ext.setFreeUnitsRemaining(0L);
+        ext.setFreeUnitsPeriodStart(PERIOD_START);
         when(teamExtRepo.findByIdForUpdate(teamId)).thenReturn(Optional.of(ext));
         when(teamExtRepo.findById(teamId)).thenReturn(Optional.of(ext));
         when(shadowRepo.findFirstByJobIdOrderByIdAsc(jobId))
@@ -1032,8 +1177,6 @@ class JobChargeServiceTest {
         return row;
     }
 
-    // --- helpers --------------------------------------------------------------------------------
-
     private static PricingPolicy stubPolicy(int minCharge, Map<JobSource, Integer> stepLimits) {
         PricingPolicy p = new PricingPolicy();
         p.setId(42L);

app/saas/src/test/java/stirling/software/saas/payg/entitlement/EntitlementServiceTest.java

@@ -26,8 +26,8 @@ import stirling.software.saas.payg.repository.WalletPolicyRepository;
 import stirling.software.saas.payg.wallet.WalletPolicy;
 
 /**
- * Unit tests for {@link EntitlementService}. Two branches (design 2026-06-11 — the free allowance
- * is a one-time lifetime grant):
+ * Unit tests for {@link EntitlementService}. Two branches (the free allowance is a per-period
+ * grant, projected onto the current period by {@code TeamBillingService} before it gets here):
  *
  * <ul>
  *   <li><b>Unsubscribed</b> — gated by the grant. Cap = grant size, spend = {@code grant −
@@ -96,7 +96,6 @@ class EntitlementServiceTest {
 
         assertThat(snap.periodCapUnits()).isEqualTo(2000L);
         assertThat(snap.periodSpendUnits()).isEqualTo(500L);
-        // 500/2000 = 25% — FULL
         assertThat(snap.state()).isEqualTo(EntitlementState.FULL);
     }
 

engine/src/stirling/agents/orchestrator.py

@@ -30,7 +30,7 @@ from stirling.contracts import (
 )
 from stirling.contracts.pdf_create import PdfCreateOrchestrateResponse
 from stirling.models import ApiModel
-from stirling.services import AppRuntime
+from stirling.services import AppRuntime, language_directive, set_reply_locale
 
 logger = logging.getLogger(__name__)
 
@@ -153,6 +153,8 @@ class OrchestratorAgent:
         )
 
     async def handle(self, request: OrchestratorRequest) -> OrchestratorResponse:
+        # Bound once; delegates and worker tasks inherit it.
+        set_reply_locale(request.locale)
         logger.info(
             "[orchestrator] handle: files=%s resume_with=%s artifacts=%s msg=%r",
             [file.name for file in request.files],
@@ -270,6 +272,7 @@ class OrchestratorAgent:
             f"User message: {request.user_message}\n"
             f"Files: {format_file_names(request.files)}\n"
             f"Available artifacts:\n{artifact_summary}"
+            f"\n{language_directive()}"
         )
 
     def _describe_artifacts(self, request: OrchestratorRequest) -> str:

engine/src/stirling/agents/pdf_comment/agent.py

@@ -30,7 +30,7 @@ from stirling.contracts.pdf_comments import (
 )
 from stirling.logging import Pretty
 from stirling.models import ApiModel
-from stirling.services import AppRuntime
+from stirling.services import AppRuntime, language_directive
 
 logger = logging.getLogger(__name__)
 
@@ -160,6 +160,8 @@ class PdfCommentAgent:
         ]
         for index, chunk in enumerate(request.chunks):
             lines.append(f"[{index}] page={chunk.page + 1} text={json.dumps(chunk.text)}")
+        # Last, after the untrusted chunk text.
+        lines.append(f"\n{language_directive()}")
         return "\n".join(lines)
 
     @staticmethod

engine/src/stirling/agents/pdf_create/agent.py

@@ -45,7 +45,7 @@ from stirling.contracts.pdf_create import (
     WrittenSections,
 )
 from stirling.models.agent_tool_models import AgentToolId, CreatePdfFromHtmlAgentParams
-from stirling.services import AppRuntime
+from stirling.services import AppRuntime, language_directive
 
 logger = logging.getLogger(__name__)
 
@@ -260,6 +260,7 @@ def _build_sections_prompt(meta: DocumentMeta, user_request: str, history: str)
 
     lines.append(f"\nConversation history:\n{history}")
     lines.append(f"\nUser request: {user_request}")
+    lines.append(f"\n{language_directive()}")
     return "\n".join(lines)
 
 
@@ -292,6 +293,7 @@ def _build_writer_prompt(plan: DocumentPlan, chunk: _Chunk) -> str:
         for point in s.key_points:
             lines.append(f"  - {point}")
 
+    lines.append(f"\n{language_directive()}")
     return "\n".join(lines)
 
 
@@ -338,6 +340,7 @@ class PdfCreateAgent:
         # ── Phase 1: plan meta ─────────────────────────────────────────────────
         logger.info("[pdf-create] phase 1/6: planning document meta")
         meta_prompt = f"Conversation history:\n{history}\n\nUser request: {request.user_message}"
+        meta_prompt += f"\n\n{language_directive()}"
         meta_result = await self._meta_planner.run(meta_prompt)
         meta = meta_result.output
 

engine/src/stirling/agents/pdf_edit.py

@@ -27,7 +27,7 @@ from stirling.contracts import (
 )
 from stirling.logging import Pretty
 from stirling.models import OPERATIONS, ApiModel, ParamToolModel, ToolEndpoint
-from stirling.services import AppRuntime, ToolChainStep, blocking, validate_tool_chain
+from stirling.services import AppRuntime, ToolChainStep, blocking, language_directive, validate_tool_chain
 
 logger = logging.getLogger(__name__)
 
@@ -357,6 +357,7 @@ class PdfEditAgent:
             f"{unavailable_line}"
             f"{repair_line}"
             f"Extracted page text:\n{format_page_text(request.page_text)}"
+            f"\n{language_directive()}"
         )
 
     # Endpoints that exist on the server and are callable via the direct API or the manual UI,

engine/src/stirling/agents/pdf_questions.py

@@ -29,7 +29,7 @@ from stirling.contracts import (
 from stirling.documents import RagCapability
 from stirling.models import PrincipalId
 from stirling.models.agent_tool_models import AgentToolId, MathAuditorAgentParams
-from stirling.services import AppRuntime, require_current_user_id
+from stirling.services import AppRuntime, language_directive, require_current_user_id
 
 logger = logging.getLogger(__name__)
 
@@ -223,6 +223,7 @@ class PdfQuestionAgent:
         forbids invented figures; the LLM only restates Verdict facts.
         """
         prompt = f"User question:\n{user_message}\n\nMath audit Verdict (JSON):\n{verdict.model_dump_json()}"
+        prompt += f"\n\n{language_directive()}"
         result = await self._math_synth_agent.run(prompt)
         return result.output
 
@@ -233,4 +234,5 @@ class PdfQuestionAgent:
             f"Files: {format_file_names(request.files)}\n"
             f"Question: {request.question}\n"
             "Pick the right retrieval tool for this question, then answer from what it returns."
+            f"\n{language_directive()}"
         )

engine/src/stirling/agents/pdf_review.py

@@ -56,7 +56,7 @@ from stirling.models.agent_tool_models import (
     PdfCommentAgentParams,
 )
 from stirling.models.tool_models import AddCommentsParams
-from stirling.services import AppRuntime, require_current_user_id
+from stirling.services import AppRuntime, language_directive, require_current_user_id
 
 # Fallback right-margin placement used when a finding has no usable
 # anchor text. A4/Letter portrait assumed.
@@ -209,6 +209,7 @@ class PdfReviewAgent:
         placement geometry to produce the JSON the ``add-comments`` tool wants.
         """
         prompt = f"User review request:\n{user_message}\n\nMath audit Verdict (JSON):\n{verdict.model_dump_json()}"
+        prompt += f"\n\n{language_directive()}"
         result = await self._localiser_agent.run(prompt)
         specs = self._build_comment_specs(verdict, result.output.comments)
         serialised = [spec.model_dump(by_alias=True, exclude_none=True) for spec in specs]
@@ -238,6 +239,7 @@ class PdfReviewAgent:
         prompt = (
             f"<user_message>{_escape_for_tag(user_message)}</user_message>\n"
             f"<verdict>{_escape_for_tag(report.model_dump_json())}</verdict>"
+            f"\n{language_directive()}"
         )
         result = await self._contradiction_localiser.run(prompt)
         specs = self._build_paired_comment_specs(report, result.output.comments)

engine/src/stirling/agents/user_spec.py

@@ -21,7 +21,7 @@ from stirling.contracts import (
     format_conversation_history,
 )
 from stirling.models import ApiModel
-from stirling.services import AppRuntime
+from stirling.services import AppRuntime, language_directive
 
 
 class UserSpecMetadata(ApiModel):
@@ -98,6 +98,7 @@ class UserSpecAgent:
             f"Edit plan summary:\n{edit_plan.summary}\n\n"
             f"Edit plan rationale:\n{edit_plan.rationale or 'None'}\n\n"
             f"Edit plan steps:\n{edit_plan.model_dump_json(indent=2)}"
+            f"\n\n{language_directive()}"
         )
 
     def _build_revision_prompt(self, request: AgentRevisionRequest, edit_plan: EditPlanResponse) -> str:
@@ -108,6 +109,7 @@ class UserSpecAgent:
             f"Edit plan summary:\n{edit_plan.summary}\n\n"
             f"Edit plan rationale:\n{edit_plan.rationale or 'None'}\n\n"
             f"Edit plan steps:\n{edit_plan.model_dump_json(indent=2)}"
+            f"\n\n{language_directive()}"
         )
 
     async def _build_edit_plan(

engine/src/stirling/contracts/orchestrator.py

@@ -42,6 +42,8 @@ class OrchestratorRequest(ApiModel):
     conversation_history: list[ConversationMessage] = Field(default_factory=list)
     artifacts: list[WorkflowArtifact] = Field(default_factory=list)
     resume_with: SupportedCapability | None = None
+    # Reply language (IETF tag); unset falls back to the message's own language.
+    locale: str | None = None
     # See `PdfEditRequest.enabled_endpoints`.
     enabled_endpoints: Annotated[list[ToolEndpoint], BeforeValidator(drop_unknown_tool_endpoints)] = Field(
         default_factory=list

engine/src/stirling/services/__init__.py

@@ -1,5 +1,6 @@
 """Shared services used by the Stirling AI runtime."""
 
+from .language import language_directive, set_reply_locale
 from .progress import (
     ProgressEmitter,
     emit_progress,
@@ -20,9 +21,11 @@ __all__ = [
     "build_runtime",
     "current_user_id",
     "emit_progress",
+    "language_directive",
     "require_current_user_id",
     "reset_progress_emitter",
     "set_progress_emitter",
+    "set_reply_locale",
     "setup_posthog_tracking",
     "validate_tool_chain",
 ]

engine/src/stirling/services/language.py

@@ -0,0 +1,23 @@
+"""Per-request reply language, bound by the orchestrator, read by prompt builders."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+_locale: ContextVar[str | None] = ContextVar("stirling_reply_locale", default=None)
+
+
+def set_reply_locale(locale: str | None) -> None:
+    _locale.set(locale)
+
+
+def language_directive() -> str:
+    """Prompt line pinning the reply language; append to any user-facing prompt."""
+    locale = _locale.get()
+    if not locale:
+        return "Write anything the user will read in the same language as their message."
+    return (
+        f"Write anything the user will read in the language of locale '{locale}', whatever "
+        "language this prompt, the documents, or the tool output are in. Only a different "
+        "language the user explicitly asks for overrides this."
+    )

engine/tests/test_reply_language.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any, cast
+
+import pytest
+
+from stirling.agents import OrchestratorAgent
+from stirling.agents.pdf_questions import PdfQuestionAgent
+from stirling.contracts import (
+    OrchestratorRequest,
+    PdfQuestionAnswerResponse,
+    PdfQuestionRequest,
+    SupportedCapability,
+)
+from stirling.services import language_directive, set_reply_locale
+from stirling.services.runtime import AppRuntime
+
+
+@pytest.fixture(autouse=True)
+def reset_locale() -> Iterator[None]:
+    set_reply_locale(None)
+    yield
+    set_reply_locale(None)
+
+
+def test_directive_falls_back_to_the_message_language() -> None:
+    assert "same language as their message" in language_directive()
+
+
+def test_directive_pins_the_bound_locale() -> None:
+    set_reply_locale("fr-FR")
+    assert "'fr-FR'" in language_directive()
+
+
+def test_orchestrator_request_carries_the_locale() -> None:
+    assert OrchestratorRequest.model_validate({"userMessage": "hi", "locale": "de-DE"}).locale == "de-DE"
+    assert OrchestratorRequest.model_validate({"userMessage": "hi"}).locale is None
+
+
+def test_question_prompt_carries_the_directive() -> None:
+    set_reply_locale("es-ES")
+    # _build_prompt ignores self, so call it off the class.
+    prompt = PdfQuestionAgent._build_prompt(cast(Any, None), PdfQuestionRequest(question="¿Cuántas páginas?"))
+    assert "'es-ES'" in prompt
+
+
+@pytest.mark.anyio
+async def test_handle_binds_the_locale_for_delegates(runtime: AppRuntime, monkeypatch: pytest.MonkeyPatch) -> None:
+    """The resume path reaches a delegate with the request's locale already bound."""
+    agent = OrchestratorAgent(runtime)
+    seen: list[str] = []
+
+    async def capture(request: OrchestratorRequest) -> PdfQuestionAnswerResponse:
+        seen.append(language_directive())
+        return PdfQuestionAnswerResponse(answer="ok")
+
+    monkeypatch.setattr(agent, "_run_pdf_question", capture)
+    await agent.handle(
+        OrchestratorRequest(
+            user_message="Combien de pages ?",
+            locale="fr-FR",
+            resume_with=SupportedCapability.PDF_QUESTION,
+        )
+    )
+    assert "'fr-FR'" in seen[0]

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

@@ -4321,7 +4321,8 @@ download = "Download"
 downloadAll = "Download all"
 downloadVersion = "Download this version"
 dropOverlay = "Drop files to upload"
-dropOverlaySub = "Files start in Local. Use 'Move to' or 'Save to cloud' to organize them into a folder."
+dropOverlaySub = "Files land in Local. Organize them into folders any time."
+dropOverlaySubFolder = "They'll be added to this folder."
 duplicate = "Duplicate"
 file = "File"
 fileInfo = "File info"
@@ -4334,12 +4335,19 @@ inPath = "in {{path}}"
 inWorkspace = "Open"
 inWorkspaceAria = "Already in workspace"
 loading = "Loading…"
-localFoldersUnavailable = "Folders are cloud-only - save a file to the cloud to organize it."
+localFolderManagedByDisk = "This folder is managed by its directory on disk."
+moveAcrossKindsBlocked = "These folders live in different places, so one can't go inside the other."
+moveIntoMountCloudSkipped_one = "{{count}} server file stayed in your files. It lives on the server, not on this disk."
+moveIntoMountCloudSkipped_other = "{{count}} server files stayed in your files. They live on the server, not on this disk."
+moveIntoMountFailed_one = "{{count}} file could not be written into the folder."
+moveIntoMountFailed_other = "{{count}} files could not be written into the folder."
+moveIntoVirtualCloudSkipped_one = "{{count}} server file was left in place. Server files can't live in browser-only folders."
+moveIntoVirtualCloudSkipped_other = "{{count}} server files were left in place. Server files can't live in browser-only folders."
 moveSkippedRemote_one = "{{count}} file couldn't be moved on the server (no permission or already deleted)."
 moveSkippedRemote_other = "{{count}} files couldn't be moved on the server (no permission or already deleted)."
 moveTo = "Move to…"
 newFolder = "New folder"
-newFolderStorageDisabled = "Server folder storage isn't enabled. Ask your admin to turn it on."
+newFolderStorageDisabled = "Server folder storage isn't enabled."
 newFolderTabUnavailable = "Switch to All or Cloud to create folders."
 offlineNoFolderEdits = "Server folder sync unavailable - folder changes are disabled. Check sign-in and storage configuration."
 open = "Open"
@@ -4347,6 +4355,7 @@ openVersionInWorkspace = "Open in workspace"
 originFilter = "Filter by source"
 refresh = "Refresh from server"
 remove = "Delete"
+removeLocalFolder = "Remove (files stay on disk)"
 removeVersion = "Remove this version"
 rename = "Rename"
 renamed = "Renamed"
@@ -4359,6 +4368,7 @@ selectAll = "Select all"
 selectAllHint = "Click to select all. Tip: hold Ctrl (or Cmd) to add files one at a time, Shift to select a range."
 selectedCount = "{{count}} selected"
 selectFile = "Select file {{name}}"
+serverFolderNeedsConnection = "Sign in to Stirling Cloud or connect a self-hosted server to use server folders."
 shareDisabledHint = "File sharing isn't enabled on this server. Ask your admin to enable it."
 shareManage = "Manage sharing"
 showDetails = "Show details"
@@ -4367,7 +4377,6 @@ summary_one = "{{count}} item"
 summary_other = "{{count}} items"
 tree = "Folders"
 upload = "Upload"
-uploadedToLocal = "Uploaded files start in Local. Use 'Save to cloud' to put them in a folder."
 uploadFromMobile = "Upload from Mobile"
 versionActions = "Version actions"
 versionCollapse = "Collapse middle versions"
@@ -4433,6 +4442,8 @@ title = "You haven't shared any files yet"
 [filesPage.error]
 actionFailed = "Could not {{action}}."
 actionFailedDetail = "Could not {{action}}: {{message}}"
+addFolderFailed = "Could not add the folder."
+addFolderFailedDetail = "Could not add the folder: {{message}}"
 cloudDeleteFailed_one = "Couldn't delete 1 file from the cloud."
 cloudDeleteFailed_other = "Couldn't delete {{count}} files from the cloud."
 deleteFolderFailed = "Could not delete folder."
@@ -4445,8 +4456,14 @@ moveFilesFailed = "Could not move files."
 moveFilesFailedDetail = "Could not move files: {{message}}"
 moveFolderFailed = "Could not move folder."
 moveFolderFailedDetail = "Could not move folder: {{message}}"
+openDiskFileFailed = "Could not open {{name}}."
+openDiskFileFailedDetail = "Could not open {{name}}: {{message}}"
+readFolderFailed = "Could not read the folder."
+readFolderFailedDetail = "Could not read the folder: {{message}}"
 removeFilesFailed = "Could not remove files."
 removeFilesFailedDetail = "Could not remove files: {{message}}"
+removeFolderFailed = "Could not remove folder."
+removeFolderFailedDetail = "Could not remove folder: {{message}}"
 uploadFilesFailed = "Could not upload files."
 uploadFilesFailedDetail = "Could not upload files: {{message}}"
 
@@ -4466,12 +4483,21 @@ activeCount = "{{count}} filters active"
 clearAll = "Clear filters"
 label = "Filters"
 
+[filesPage.folderKind]
+local = "Local folder"
+virtual = "Browser folder"
+
 [filesPage.folderName]
 cancel = "Cancel"
 error = "Could not save folder. Try again."
 label = "Folder name"
 placeholder = "Folder name"
 
+[filesPage.folderOrigin]
+diskHint = "A folder mounted from a directory on your disk"
+serverHint = "A folder stored on the Stirling server"
+virtualHint = "A folder that lives only in this browser"
+
 [filesPage.moveDialog]
 cancel = "Cancel"
 confirm = "Move here"
@@ -4485,10 +4511,16 @@ newFolderPlaceholder = "Folder name"
 newFolderToggle = "Create new folder…"
 title = "Move to folder"
 
+[filesPage.newFolderMenu]
+addExisting = "Add local folder"
+server = "New folder on the server"
+serverHint = "Synced to your account, available wherever you sign in."
+
 [filesPage.origin]
 all = "All sources"
 cloud = "Cloud"
 cloudHint = "Stored on the Stirling server"
+diskHint = "A file in the mounted folder on your disk"
 local = "Local"
 localHint = "Only stored in this browser"
 shared = "Shared"
@@ -6097,7 +6129,7 @@ freeTitle = "Unlimited PDF editing"
 
 [payg.free.hero]
 barAria = "Free PDFs remaining"
-capSuffix = "of {{limit}} free PDFs left"
+capSuffix = "of {{limit}} free PDFs left this month"
 metaCategories = "Automation · AI · API requests"
 
 [payg.free.member]
@@ -6163,7 +6195,7 @@ leader = "Team owner"
 member = "Member"
 
 [payg.signupRequired]
-body = "Stirling PDF gives every signed-up account 500 free operations, enough to keep most workflows humming without paying a cent. You're currently using Stirling as a guest, which doesn't include billable tools like AI, automations, or hosted processing."
+body = "Stirling PDF gives every signed-up account 500 free operations a month, enough to keep most workflows humming without paying a cent. You're currently using Stirling as a guest, which doesn't include billable tools like AI, automations, or hosted processing."
 cancel = "Not now"
 cta = "Sign up free"
 subtext = "Creating an account is free and takes a few seconds. No credit card required."
@@ -6849,7 +6881,7 @@ name = "Free"
 [plan.freeLimit]
 cta = "View Processor Plan"
 dismiss = "Maybe Later"
-message = "That's your whole free allowance for automation, AI and the API. Seriously impressive! Keep the momentum going for just pennies a day."
+message = "That's your whole free allowance for automation, AI and the API this month. Seriously impressive! It resets next month, or keep the momentum going now for just pennies a day."
 title = "Woah, {{total}} PDFs Processed!"
 
 [plan.highlights]
@@ -7431,17 +7463,17 @@ reachedTitle = "Monthly spend limit reached"
 title = "Couldn't open Stripe portal"
 
 [portal.billing.walletMeter]
-barAria = "Free PDFs remaining"
-capSuffix_one = "of {{allowance}} free PDF left"
-capSuffix_other = "of {{allowance}} free PDFs left"
+barAria = "Free credits remaining"
+capSuffix_one = "of {{allowance}} free credit left this month"
+capSuffix_other = "of {{allowance}} free credits left this month"
 eyebrow = "Processor trial"
 statusLabel_one = "{{used}} used"
 statusLabel_other = "{{used}} used"
 sub = "Use the PDF Editor for free. Pay to process PDFs automatically."
-title_one = "{{allowance}} free credit to start"
-title_other = "{{allowance}} free credits to start"
-titleWithRate_one = "{{allowance}} free credit, then {{rate}} per PDF"
-titleWithRate_other = "{{allowance}} free credits, then {{rate}} per PDF"
+title_one = "{{allowance}} free credit every month"
+title_other = "{{allowance}} free credits every month"
+titleWithRate_one = "{{allowance}} free credit every month, then {{rate}} per PDF"
+titleWithRate_other = "{{allowance}} free credits every month, then {{rate}} per PDF"
 
 [portal.components.billingUnit]
 approval = "approval"
@@ -8426,11 +8458,14 @@ platform = "PDF Platform"
 processor = "PDF Processor"
 
 [portal.pipelines]
-subtitle = "Every automated document pipeline on the backend: an ordered chain of operations over a set of sources, run on a trigger. Click a row for its steps and sources."
+subtitle = "Automate your document workflows. Start from a template for a simple, guided setup, or build a custom pipeline from scratch. Enforce any pipeline as a policy to run it on every document."
 title = "Pipelines"
 
 [portal.pipelines.actions]
-newPipeline = "New pipeline"
+newCustomPipeline = "New custom pipeline"
+
+[portal.pipelines.all]
+title = "All pipelines"
 
 [portal.pipelines.builder]
 activate = "Activate"
@@ -8489,6 +8524,9 @@ output-uncertain = "May not run: output depends on setup"
 source-mismatch = "Input is {{produced}}, needs {{accepts}}"
 undeclared-operation = "Can't check what this step accepts"
 
+[portal.pipelines.builder.icon]
+label = "Change icon"
+
 [portal.pipelines.composer]
 addTool = "Add a tool"
 create = "Create pipeline"
@@ -8538,6 +8576,11 @@ connectSource = "Connect a source"
 description = "Create your first pipeline: pick the sources it runs over, chain the operations, and choose where output goes."
 title = "No pipelines yet"
 
+[portal.pipelines.enforce]
+desc = "Runs automatically; members can't turn it off"
+info = "What enforcing as a policy means"
+label = "Enforce as policy"
+
 [portal.pipelines.graph]
 addFirstTool = "Add a tool"
 dragHint = "Drop on a line to move it"
@@ -8597,6 +8640,11 @@ sources = "Sources"
 status = "Status"
 steps = "Steps"
 trigger = "Trigger"
+type = "Type"
+
+[portal.pipelines.templates]
+setUp = "Set up"
+title = "Templates"
 
 [portal.pipelines.trigger]
 editor-export = "Every export"
@@ -8605,10 +8653,12 @@ folder-watch = "Folder watch"
 manual = "Manual"
 schedule = "Scheduled"
 
+[portal.pipelines.type]
+pipeline = "Pipeline"
+policy = "Policy"
+
 [portal.policies]
-defaultName = "{{category}} Policy"
-subtitle = "Standing automations that enforce a tool pipeline on every document. Each policy fires on upload or export, runs its tool chain, and saves the enforced version alongside the original."
-title = "Policies"
+defaultName = "{{category}} Pipeline"
 
 [portal.policies.card]
 comingSoon = "Upgrade to Enterprise"
@@ -8734,7 +8784,7 @@ summary = "Detects and redacts PII, strips active content (JavaScript), and wate
 2 = "Watermark"
 
 [portal.policies.detail]
-enforces = "Enforces"
+enforces = "Steps"
 onEveryExport = "On every export"
 onEveryUpload = "On every upload"
 outputAsNewFile = "as a new file"
@@ -8754,13 +8804,13 @@ resume = "Resume"
 runNow = "Run now"
 
 [portal.policies.detail.clearHistory]
-body = "This policy will forget every file it has already processed and reprocess everything currently in its sources on the next run. The files themselves are not changed. This cannot be undone."
+body = "This pipeline will forget every file it has already processed and reprocess everything currently in its sources on the next run. The files themselves are not changed. This cannot be undone."
 cancel = "Cancel"
 confirm = "Clear history"
 title = "Clear processed history?"
 
 [portal.policies.detail.emptyActivity]
-description = "Documents will appear here once this policy runs."
+description = "Documents will appear here once this pipeline runs."
 title = "No activity yet"
 
 [portal.policies.endpoints]
@@ -8772,11 +8822,6 @@ flatten = "Flatten"
 ocrPdf = "OCR"
 sanitizePdf = "Remove JavaScript"
 
-[portal.policies.offline]
-description = "Your policies are saved and will appear once the connection is restored."
-retry = "Retry"
-title = "Backend unavailable"
-
 [portal.policies.operations]
 change = "Change what this step does"
 noResults = "No step matches that. Try a product name, or \"scan\", \"notify\", \"attach\"."
@@ -8975,7 +9020,7 @@ label = "Trigger a Zap or Make scenario"
 [portal.policies.stats]
 activeFor = "Active"
 dataProcessed = "Data processed"
-docsEnforced = "Docs enforced"
+docsEnforced = "Docs processed"
 
 [portal.policies.status]
 active = "Active"
@@ -9005,10 +9050,9 @@ policy = "Policy"
 status = "Status"
 
 [portal.policies.wizard.actions]
-back = "Back"
 cancel = "Cancel"
-continue = "Continue"
-enablePolicy = "Enable policy"
+customise = "Customise"
+enablePolicy = "Create pipeline"
 saveChanges = "Save changes"
 
 [portal.policies.wizard.capability.classify]
@@ -9049,47 +9093,14 @@ labelsHeading = "Classification labels"
 
 [portal.policies.wizard.errors]
 noTools = "Enable at least one tool in the workflow first."
-saveFailed = "Couldn't save the policy. Please try again."
-
-[portal.policies.wizard.output]
-heading = "Output & run"
-
-[portal.policies.wizard.output.filenameRule]
-autoNumber = "Auto-number"
-label = "Filename rule"
-placeholder = "Text to add (optional)"
-prefix = "Prefix"
-suffix = "Suffix"
-
-[portal.policies.wizard.output.outputAs]
-label = "Output as"
-newFile = "New file"
-newVersion = "New version"
-
-[portal.policies.wizard.output.runOn]
-export = "Export"
-helper = "When the policy fires: on upload, or before export."
-label = "Run on"
-upload = "Upload"
-
-[portal.policies.wizard.settings]
-heading = "Settings"
-
-[portal.policies.wizard.sources]
-heading = "Sources"
-loading = "Loading sources…"
-
-[portal.policies.wizard.tabs]
-ariaLabel = "Setup steps"
-settings = "Settings"
-workflow = "Actions"
+saveFailed = "Couldn't save the pipeline. Please try again."
 
 [portal.policies.wizard.title]
-edit = "Edit {{category}} policy"
-setUp = "Set up {{category}} policy"
+edit = "Edit {{category}} pipeline"
+setUp = "Set up {{category}} pipeline"
 
 [portal.policies.wizard.workflow]
-description = "Choose what this policy does to every document it processes."
+description = "Choose what this pipeline does to every document it processes."
 
 [portal.policySummary.action]
 setUp = "Set up"

frontend/editor/src-tauri/capabilities/default.json

@@ -6,6 +6,12 @@
   "permissions": [
     "core:default",
     "core:window:allow-destroy",
+    "core:window:allow-minimize",
+    "core:window:allow-toggle-maximize",
+    "core:window:allow-internal-toggle-maximize",
+    "core:window:allow-close",
+    "core:window:allow-is-maximized",
+    "core:window:allow-start-dragging",
     "http:default",
     {
       "identifier": "http:allow-fetch",
@@ -39,6 +45,18 @@
       "identifier": "fs:allow-read-file",
       "allow": [{ "path": "**" }]
     },
+    {
+      "identifier": "fs:allow-read-dir",
+      "allow": [{ "path": "**" }]
+    },
+    {
+      "identifier": "fs:allow-stat",
+      "allow": [{ "path": "**" }]
+    },
+    {
+      "identifier": "fs:allow-mkdir",
+      "allow": [{ "path": "**" }]
+    },
     {
       "identifier": "fs:allow-write-file",
       "allow": [{ "path": "**" }]

frontend/editor/src-tauri/src/commands/window.rs

@@ -48,8 +48,11 @@ fn build_window(app: &AppHandle, label: &str, url: &str) -> Result<WebviewWindow
     // dir (and thus IndexedDB / localStorage / cookies). macOS (WKWebView) and
     // Linux (WebKitGTK) don't have this constraint, so the arg is Windows-only.
     #[cfg(target_os = "windows")]
-    let builder =
-        builder.additional_browser_args("--enable-features=CertVerifierBuiltinFeature");
+    let builder = builder
+        .additional_browser_args("--enable-features=CertVerifierBuiltinFeature")
+        // Windows: no native title bar; the frontend draws its own (WindowTitleBar).
+        // macOS/Linux keep native decorations.
+        .decorations(false);
 
     builder.build().map_err(|e| e.to_string())
 }

frontend/editor/src-tauri/src/lib.rs

@@ -146,6 +146,17 @@ pub fn run() {
     .setup(|app| {
       add_log("🚀 Tauri app setup started".to_string());
 
+      // Windows: drop the native title bar so the in-app custom title bar
+      // (window controls + drag region) takes over. Runtime toggle because the
+      // main window is defined in tauri.conf.json; spawned windows set it at
+      // build time in window.rs. macOS/Linux keep their native decorations.
+      #[cfg(target_os = "windows")]
+      {
+        if let Some(window) = app.get_webview_window(MAIN_WINDOW_LABEL) {
+          let _ = window.set_decorations(false);
+        }
+      }
+
       // Files passed on the command line at first launch load into the main
       // window once the frontend mounts.
       let args: Vec<String> = std::env::args().collect();

frontend/editor/src/cloud/components/onboarding/saasFlowResolver.ts

@@ -5,7 +5,7 @@ import {
 } from "@app/components/onboarding/onboardingSlideTypes";
 
 export interface SaasFlowInputs {
-  /** Free-tier wallet with one-time allowance remaining — show the usage meter. */
+  /** Free-tier wallet with allowance remaining this period — show the usage meter. */
   showUsageSlide: boolean;
   /** Team leaders only — invited members and anonymous guests skip the team slide. */
   showTeamSlide: boolean;

frontend/editor/src/cloud/components/shared/FreeLimitReachedModal.tsx

@@ -138,7 +138,7 @@ export function FreeLimitReachedModal({ onClose }: FreeLimitReachedModalProps) {
               <div className={`${styles.bodyCopy} ${styles.bodyCopyInner}`}>
                 {t(
                   "plan.freeLimit.message",
-                  "That's your whole free allowance for automation, AI and the API. Seriously impressive! Keep the momentum going for just pennies a day.",
+                  "That's your whole free allowance for automation, AI and the API this month. Seriously impressive! It resets next month, or keep the momentum going now for just pennies a day.",
                 )}
               </div>
             </div>

frontend/editor/src/cloud/components/shared/config/configSections/PaygFree.tsx

@@ -9,14 +9,13 @@
  * watermarks, compression — are unmetered, no matter where they're triggered
  * from. The distinction is the <em>type of work</em> (manual tool vs
  * automation / AI / API), not where the click happens, because automation and
- * AI also have UI surfaces. The one-time free grant (default 500) applies
- * <em>only</em> to the three billable categories — it is a lifetime allowance,
- * not a monthly one, and a team keeps any unused portion after subscribing.
+ * AI also have UI surfaces. The free grant applies <em>only</em> to the three
+ * billable categories, and resets each billing period.
  *
  * <p>Layout: a slim <b>Editor plan</b> card (always-free tools only — no dates,
  * no metered split) on top, then a single <b>Processor plan</b> card that
- * two-columns the upgrade pitch + benefits (left) against the one-time free
- * meter stacked over the call-to-action (right).
+ * two-columns the upgrade pitch + benefits (left) against the free-grant meter
+ * stacked over the call-to-action (right).
  *
  * <p>Two variants:
  *   - {@link PaygFreeLeader} — the right column's CTA opens the upgrade modal.
@@ -47,8 +46,6 @@ import {
   type FreeSnapshot,
 } from "@app/components/shared/config/configSections/usageMeters";
 
-// ─── Editor plan card (always-free tools only) ────────────────────────────
-
 interface EditorPlanCardProps {
   /** Role pill text on the right. */
   pill: string;
@@ -58,8 +55,8 @@ interface EditorPlanCardProps {
 
 /**
  * The top card: the free Editor plan. Manual tools only, no billing window —
- * the one-time grant lives in the Processor card below, so there's no period
- * to show here.
+ * the metered grant lives in the Processor card below, so there's no period to
+ * show here.
  */
 function EditorPlanCard({ pill, leader }: EditorPlanCardProps) {
   const { t } = useTranslation();
@@ -93,8 +90,6 @@ function EditorPlanCard({ pill, leader }: EditorPlanCardProps) {
   );
 }
 
-// ─── Processor plan card (two-column: pitch + benefits | meter + CTA) ──────
-
 interface ProcessorCardProps {
   snap: FreeSnapshot;
   /** Leaders get the live CTA; members get the ask-owner note. */
@@ -207,8 +202,6 @@ function ProcessorCard({ snap, isLeader, onTurnOn }: ProcessorCardProps) {
   );
 }
 
-// ─── Free LEADER ──────────────────────────────────────────────────────────
-
 export interface PaygFreeLeaderProps {
   /**
    * Called when the user finishes the {@link UpgradeModal} checkout flow.
@@ -265,8 +258,6 @@ function PaygFreeLeaderInner({ onUpgraded }: PaygFreeLeaderProps = {}) {
   );
 }
 
-// ─── Free MEMBER ──────────────────────────────────────────────────────────
-
 function PaygFreeMemberInner() {
   useRenderCount("PaygFreeMember");
   const { t } = useTranslation();

frontend/editor/src/cloud/components/shared/config/configSections/UpgradeModal.tsx

@@ -69,10 +69,9 @@ interface UpgradeModalProps {
   /** ISO 4217 currency code for the cap input. Default USD. */
   currency?: "USD" | "EUR" | "GBP";
   /**
-   * The team's one-time free grant in documents — the real {@code
+   * The team's free grant in documents per billing period — the real {@code
    * wallet.freeAllowance}, threaded from the free-leader view so the step copy
-   * quotes the backend's number instead of a hardcoded one. A lifetime grant,
-   * not a monthly one.
+   * quotes the backend's number instead of a hardcoded one.
    */
   freeLimit: number;
   /**

frontend/editor/src/cloud/components/shared/config/configSections/usageMeters.tsx

@@ -17,12 +17,10 @@ import {
 import "@app/components/shared/config/configSections/Payg.css";
 import "@app/components/shared/config/configSections/PaygFree.css";
 
-// ─── One-time free grant meter ──────────────────────────────────────────────
-
 export interface FreeSnapshot {
-  /** One-time free documents used so far (grant − remaining). */
+  /** Free documents used so far this period (grant − remaining). */
   billableUsed: number;
-  /** The team's one-time free grant size in documents. */
+  /** The team's free grant size in documents, per billing period. */
   billableLimit: number;
 }
 
@@ -64,9 +62,11 @@ export function FreeMeterPanel({ snap }: { snap: FreeSnapshot }) {
       pct={pct}
       barLabel={t("payg.free.hero.barAria", "Free PDFs remaining")}
       figure={remaining.toLocaleString()}
-      capSuffix={t("payg.free.hero.capSuffix", "of {{limit}} free PDFs left", {
-        limit: snap.billableLimit.toLocaleString(),
-      })}
+      capSuffix={t(
+        "payg.free.hero.capSuffix",
+        "of {{limit}} free PDFs left this month",
+        { limit: snap.billableLimit.toLocaleString() },
+      )}
       statusLabel={stateLabel}
       meta={
         <span>
@@ -77,8 +77,6 @@ export function FreeMeterPanel({ snap }: { snap: FreeSnapshot }) {
   );
 }
 
-// ─── Monthly spend-cap meter ────────────────────────────────────────────────
-
 export interface SpendCapSnapshot {
   /** Money spent so far this billing period, in major currency units. */
   spent: number;
@@ -106,8 +104,8 @@ export function spendCapSnapshotFromWallet(
 }
 
 /**
- * Sibling of {@link FreeMeterPanel} for the money cap rather than the one-time
- * free grant. Shares the same bar/status styling and the cap-state labels
+ * Sibling of {@link FreeMeterPanel} for the money cap rather than the free
+ * grant. Shares the same bar/status styling and the cap-state labels
  * ({@code payg.state.*}) used by the Plan hero, so it reads as the same meter.
  */
 export function SpendCapMeterPanel({ snap }: { snap: SpendCapSnapshot }) {
@@ -149,8 +147,6 @@ export function SpendCapMeterPanel({ snap }: { snap: SpendCapSnapshot }) {
   );
 }
 
-// ─── Prepaid bundle capacity meter ──────────────────────────────────────────
-
 export interface PrepaidSnapshot {
   /** Prepaid units still available across the team's in-term pools. */
   remaining: number;

frontend/editor/src/cloud/hooks/useFreeCreditsSummary.ts

@@ -13,10 +13,8 @@ function toCredits(
   freeRemaining: number,
   freeAllowance: number,
 ): CachedCredits {
-  // Free teams only. The grant is a lifetime pool that survives subscribing, so
-  // a paying team would otherwise sit on a permanent "0 of 500" in red while
-  // nothing is wrong. Plan draws the same line — subscribed teams get the
-  // spend-vs-cap meter there, and admins get usage in the processor.
+  // Free teams only: a payer's headline number is spend against cap, and a
+  // draining free meter beside a live invoice reads as a problem.
   if (status === "subscribed") return null;
   return { remaining: freeRemaining, total: freeAllowance };
 }

frontend/editor/src/cloud/services/paygErrorInterceptor.ts

@@ -4,7 +4,7 @@
  *
  * <ul>
  *   <li>{@code 402 FEATURE_DEGRADED} — an authenticated (JWT/web) team hit a
- *       billable feature it no longer has: a free team that spent its one-time
+ *       billable feature it no longer has: a free team that spent this period's
  *       allowance, or a subscribed team over its monthly spending cap. Which
  *       one is told by the {@code subscribed} field on the body.</li>
  *   <li>{@code 402 PAYG_LIMIT_REACHED} — same situation reached via an API key

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

@@ -20,7 +20,13 @@ import CreateNewFolderIcon from "@mui/icons-material/CreateNewFolder";
 import SearchIcon from "@mui/icons-material/Search";
 
 import { FileId } from "@app/types/file";
-import { FolderId, FolderRecord, ROOT_FOLDER_ID } from "@app/types/folder";
+import {
+  FolderId,
+  FolderRecord,
+  ROOT_FOLDER_ID,
+  folderKind,
+} from "@app/types/folder";
+import type { DiskFileEntry } from "@app/services/localFolderContents";
 import { useFolders } from "@app/contexts/FolderContext";
 import { usePolicyFileBadges } from "@app/hooks/usePolicyFileBadges";
 import { StirlingFileStub } from "@app/types/fileContext";
@@ -36,20 +42,64 @@ import { FileOriginBadge } from "@app/components/filesPage/FileOriginBadge";
 import { FolderThumbnail } from "@app/components/filesPage/FolderThumbnail";
 import { findFolderIcon } from "@app/components/filesPage/folderIcons";
 import { FolderAppearancePicker } from "@app/components/filesPage/FolderAppearancePicker";
-import { useLazyThumbnail } from "@app/hooks/useLazyThumbnail";
+import {
+  useLazyThumbnail,
+  useDiskThumbnail,
+} from "@app/hooks/useLazyThumbnail";
 import { useFileActionIcons } from "@app/hooks/useFileActionIcons";
 import { useFileActionTerminology } from "@app/hooks/useFileActionTerminology";
 import type { FilesPageSortMode } from "@app/contexts/FilesPageContext";
 import { OpenInNewWindowMenuItem } from "@app/components/filesPage/OpenInNewWindowMenuItem";
 
+/**
+ * The origin badge a folder wears, mirroring the one its files would: a server folder
+ * is Cloud, a virtual folder is Local (this browser), a mounted folder is On disk.
+ */
+function useFolderOriginBadge(folder: FolderRecord): {
+  origin: "cloud" | "local";
+  tooltip: string;
+} {
+  const { t } = useTranslation();
+  switch (folderKind(folder)) {
+    case "virtual":
+      return {
+        origin: "local",
+        tooltip: t(
+          "filesPage.folderOrigin.virtualHint",
+          "A folder that lives only in this browser",
+        ),
+      };
+    case "local":
+      return {
+        // Same mark as a virtual folder: what matters is that it lives on
+        // this device, not which corner of it. The tooltip says which.
+        origin: "local",
+        tooltip: t(
+          "filesPage.folderOrigin.diskHint",
+          "A folder mounted from a directory on your disk",
+        ),
+      };
+    default:
+      return {
+        origin: "cloud",
+        tooltip: t(
+          "filesPage.folderOrigin.serverHint",
+          "A folder stored on the Stirling server",
+        ),
+      };
+  }
+}
+
 export type FilesPageViewMode = "grid" | "list";
 
 export interface FilesPageEntry {
-  kind: "folder" | "file";
+  kind: "folder" | "file" | "diskFile";
   folder?: FolderRecord;
   /** Number of files inside this folder (folder entries only). */
   folderFileCount?: number;
   file?: StirlingFileStub;
+  /** A file read straight off a mounted directory (kind "diskFile"). */
+  disk?: DiskFileEntry;
   /** Parent breadcrumb path for search results outside the current folder. */
   parentPath?: string;
 }
@@ -66,6 +116,7 @@ interface FileGridProps {
   onOpenFolder: (id: FolderId) => void;
   /** "Add to workspace". */
   onOpenFile: (file: StirlingFileStub) => void;
+  onOpenDiskFile?: (entry: DiskFileEntry) => void;
   onMoveFiles: (
     fileIds: FileId[],
     targetFolderId: FolderId | null,
@@ -383,6 +434,7 @@ function GridView(props: FileGridProps) {
     onSelectFile,
     onOpenFolder,
     onOpenFile,
+    onOpenDiskFile,
     onMoveFiles,
     onMoveFolder,
     onRenameFolder,
@@ -414,6 +466,15 @@ function GridView(props: FileGridProps) {
             />
           );
         }
+        if (entry.kind === "diskFile" && entry.disk) {
+          return (
+            <DiskFileCard
+              key={`disk-${entry.disk.path}`}
+              entry={entry.disk}
+              onOpen={() => onOpenDiskFile?.(entry.disk!)}
+            />
+          );
+        }
         if (entry.kind === "file" && entry.file) {
           return (
             <FileCard
@@ -470,6 +531,12 @@ function FolderCard({
 }: FolderCardProps) {
   const { t } = useTranslation();
   const { serverReachable, setError } = useFolders();
+  // Only a server folder can go offline: the other kinds take their name, look and
+  // lifetime from elsewhere, so their edit items are hidden rather than disabled.
+  const kind = folderKind(folder);
+  const originBadge = useFolderOriginBadge(folder);
+  const editsDisabled = kind === "server" && !serverReachable;
+  const editsHidden = kind === "local";
   const offlineHint = t(
     "filesPage.offlineNoFolderEdits",
     "Offline - folder changes are disabled.",
@@ -517,9 +584,7 @@ function FolderCard({
         e.dataTransfer.effectAllowed = "move";
       }}
       {...dropHandlers}
-      className={`files-page-card is-folder${
-        isDropTarget ? " is-drop-target" : ""
-      }`}
+      className={`files-page-card is-folder${isDropTarget ? " is-drop-target" : ""}`}
       onDoubleClick={onOpen}
       onContextMenu={(e) => {
         e.preventDefault();
@@ -540,6 +605,13 @@ function FolderCard({
           fileCount={fileCount}
           iconGlyph={findFolderIcon(folder.icon)?.glyph}
         />
+        <div className="files-page-card-origin">
+          <FileOriginBadge
+            origin={originBadge.origin}
+            tooltip={originBadge.tooltip}
+            compact
+          />
+        </div>
       </div>
       <div className="files-page-card-body">
         <div className="files-page-card-name" title={folder.name}>
@@ -577,33 +649,51 @@ function FolderCard({
             >
               {t("filesPage.open", "Open")}
             </Menu.Item>
-            <Menu.Item
-              leftSection={<DriveFileRenameOutlineIcon fontSize="small" />}
-              onClick={onRename}
-              disabled={!serverReachable}
-              title={!serverReachable ? offlineHint : undefined}
-            >
-              {t("filesPage.rename", "Rename")}
-            </Menu.Item>
-            <Menu.Divider />
-            <Menu.Label>
-              {t("filesPage.appearance.title", "Appearance")}
-            </Menu.Label>
-            <FolderAppearancePicker
-              folder={folder}
-              onChange={onChangeAppearance}
-              disabled={!serverReachable}
-            />
-            <Menu.Divider />
-            <Menu.Item
-              color="red"
-              leftSection={<DeleteIcon fontSize="small" />}
-              onClick={onDelete}
-              disabled={!serverReachable}
-              title={!serverReachable ? offlineHint : undefined}
-            >
-              {t("filesPage.deleteFolder", "Delete folder")}
-            </Menu.Item>
+            {/* Only a mount root can be removed; a subdirectory is the
+                disk's, and the app never deletes directories. */}
+            {editsHidden && folder.parentFolderId === null && (
+              <Menu.Item
+                color="red"
+                leftSection={<DeleteIcon fontSize="small" />}
+                onClick={onDelete}
+              >
+                {t(
+                  "filesPage.removeLocalFolder",
+                  "Remove (files stay on disk)",
+                )}
+              </Menu.Item>
+            )}
+            {!editsHidden && (
+              <>
+                <Menu.Item
+                  leftSection={<DriveFileRenameOutlineIcon fontSize="small" />}
+                  onClick={onRename}
+                  disabled={editsDisabled}
+                  title={editsDisabled ? offlineHint : undefined}
+                >
+                  {t("filesPage.rename", "Rename")}
+                </Menu.Item>
+                <Menu.Divider />
+                <Menu.Label>
+                  {t("filesPage.appearance.title", "Appearance")}
+                </Menu.Label>
+                <FolderAppearancePicker
+                  folder={folder}
+                  onChange={onChangeAppearance}
+                  disabled={editsDisabled}
+                />
+                <Menu.Divider />
+                <Menu.Item
+                  color="red"
+                  leftSection={<DeleteIcon fontSize="small" />}
+                  onClick={onDelete}
+                  disabled={editsDisabled}
+                  title={editsDisabled ? offlineHint : undefined}
+                >
+                  {t("filesPage.deleteFolder", "Delete folder")}
+                </Menu.Item>
+              </>
+            )}
           </Menu.Dropdown>
         </Menu>
       </div>
@@ -908,9 +998,7 @@ function FileCard({
       onKeyDown={(e) => {
         if (e.key === "Enter") onDoubleClick();
       }}
-      className={`files-page-card${isSelected ? " is-selected" : ""}${
-        isInWorkspace ? " is-in-workspace" : ""
-      }`}
+      className={`files-page-card${isSelected ? " is-selected" : ""}${isInWorkspace ? " is-in-workspace" : ""}`}
     >
       {isInWorkspace && (
         <span
@@ -1011,6 +1099,7 @@ function ListView(
     onSetSelection,
     onOpenFolder,
     onOpenFile,
+    onOpenDiskFile,
     onMoveFiles,
     onMoveFolder,
     onRenameFolder,
@@ -1129,6 +1218,15 @@ function ListView(
             />
           );
         }
+        if (entry.kind === "diskFile" && entry.disk) {
+          return (
+            <DiskFileRow
+              key={`disk-${entry.disk.path}`}
+              entry={entry.disk}
+              onOpen={() => onOpenDiskFile?.(entry.disk!)}
+            />
+          );
+        }
         if (entry.kind === "file" && entry.file) {
           return (
             <FileRow
@@ -1183,6 +1281,11 @@ function FolderRow({
 }: FolderRowProps) {
   const { t } = useTranslation();
   const { serverReachable, setError } = useFolders();
+  // Kinds gate the edit items, as in FolderCard.
+  const kind = folderKind(folder);
+  const originBadge = useFolderOriginBadge(folder);
+  const editsDisabled = kind === "server" && !serverReachable;
+  const editsHidden = kind === "local";
   const offlineHint = t(
     "filesPage.offlineNoFolderEdits",
     "Offline - folder changes are disabled.",
@@ -1278,8 +1381,19 @@ function FolderRow({
             </span>
           )}
         </span>
+        <FileOriginBadge
+          origin={originBadge.origin}
+          tooltip={originBadge.tooltip}
+          compact
+        />
+      </span>
+      <span role="gridcell">
+        {kind === "virtual"
+          ? t("filesPage.folderKind.virtual", "Browser folder")
+          : kind === "local"
+            ? t("filesPage.folderKind.local", "Local folder")
+            : t("filesPage.folder", "Folder")}
       </span>
-      <span role="gridcell">{t("filesPage.folder", "Folder")}</span>
       <span role="gridcell">
         {fileCount === 0
           ? "-"
@@ -1308,33 +1422,51 @@ function FolderRow({
             >
               {t("filesPage.open", "Open")}
             </Menu.Item>
-            <Menu.Item
-              leftSection={<DriveFileRenameOutlineIcon fontSize="small" />}
-              onClick={onRename}
-              disabled={!serverReachable}
-              title={!serverReachable ? offlineHint : undefined}
-            >
-              {t("filesPage.rename", "Rename")}
-            </Menu.Item>
-            <Menu.Divider />
-            <Menu.Label>
-              {t("filesPage.appearance.title", "Appearance")}
-            </Menu.Label>
-            <FolderAppearancePicker
-              folder={folder}
-              onChange={onChangeAppearance}
-              disabled={!serverReachable}
-            />
-            <Menu.Divider />
-            <Menu.Item
-              color="red"
-              leftSection={<DeleteIcon fontSize="small" />}
-              onClick={onDelete}
-              disabled={!serverReachable}
-              title={!serverReachable ? offlineHint : undefined}
-            >
-              {t("filesPage.deleteFolder", "Delete folder")}
-            </Menu.Item>
+            {/* Only a mount root can be removed; a subdirectory is the
+                disk's, and the app never deletes directories. */}
+            {editsHidden && folder.parentFolderId === null && (
+              <Menu.Item
+                color="red"
+                leftSection={<DeleteIcon fontSize="small" />}
+                onClick={onDelete}
+              >
+                {t(
+                  "filesPage.removeLocalFolder",
+                  "Remove (files stay on disk)",
+                )}
+              </Menu.Item>
+            )}
+            {!editsHidden && (
+              <>
+                <Menu.Item
+                  leftSection={<DriveFileRenameOutlineIcon fontSize="small" />}
+                  onClick={onRename}
+                  disabled={editsDisabled}
+                  title={editsDisabled ? offlineHint : undefined}
+                >
+                  {t("filesPage.rename", "Rename")}
+                </Menu.Item>
+                <Menu.Divider />
+                <Menu.Label>
+                  {t("filesPage.appearance.title", "Appearance")}
+                </Menu.Label>
+                <FolderAppearancePicker
+                  folder={folder}
+                  onChange={onChangeAppearance}
+                  disabled={editsDisabled}
+                />
+                <Menu.Divider />
+                <Menu.Item
+                  color="red"
+                  leftSection={<DeleteIcon fontSize="small" />}
+                  onClick={onDelete}
+                  disabled={editsDisabled}
+                  title={editsDisabled ? offlineHint : undefined}
+                >
+                  {t("filesPage.deleteFolder", "Delete folder")}
+                </Menu.Item>
+              </>
+            )}
           </Menu.Dropdown>
         </Menu>
       </span>
@@ -1402,9 +1534,7 @@ function FileRow({
       onKeyDown={(e) => {
         if (e.key === "Enter") onOpen();
       }}
-      className={`files-page-list-row${isSelected ? " is-selected" : ""}${
-        isInWorkspace ? " is-in-workspace" : ""
-      }`}
+      className={`files-page-list-row${isSelected ? " is-selected" : ""}${isInWorkspace ? " is-in-workspace" : ""}`}
     >
       {/* Each direct child is a gridcell: a role="row" may only own cells, so the
           checkbox and the actions menu have to sit inside one.
@@ -1516,3 +1646,194 @@ function FileRow({
 
 // Re-export root constant for caller convenience
 export { ROOT_FOLDER_ID };
+
+/**
+ * No stub behind it, so no selection, move, rename or delete: the disk owns the
+ * file and the only affordance is adding it to the workspace.
+ */
+function DiskFileCard({
+  entry,
+  onOpen,
+}: {
+  entry: DiskFileEntry;
+  onOpen: () => void;
+}) {
+  const { t } = useTranslation();
+  const thumbnail = useDiskThumbnail(entry);
+  const extension = entry.name.includes(".")
+    ? entry.name.split(".").pop()!.toUpperCase()
+    : "";
+  const isPdf = extension === "PDF";
+  return (
+    <div
+      className="files-page-card"
+      role="listitem"
+      tabIndex={0}
+      onDoubleClick={onOpen}
+      onKeyDown={(e) => {
+        if (e.key === "Enter") onOpen();
+      }}
+      title={entry.path}
+    >
+      <div className="files-page-card-thumb">
+        {thumbnail ? (
+          <img src={thumbnail} alt="" draggable={false} />
+        ) : (
+          <div className="files-page-card-thumb-fallback">
+            {isPdf ? (
+              <PictureAsPdfIcon style={{ fontSize: "2rem" }} />
+            ) : (
+              <InsertDriveFileIcon style={{ fontSize: "2rem" }} />
+            )}
+            <span>{extension || "FILE"}</span>
+          </div>
+        )}
+        <div className="files-page-card-origin">
+          <FileOriginBadge
+            origin="local"
+            tooltip={t(
+              "filesPage.origin.diskHint",
+              "A file in the mounted folder on your disk",
+            )}
+            compact
+          />
+        </div>
+      </div>
+      <div className="files-page-card-body">
+        <div className="files-page-card-name" title={entry.name}>
+          {entry.name}
+        </div>
+        <div className="files-page-card-meta">
+          <span>{formatFileSize(entry.sizeBytes)}</span>
+          <span>·</span>
+          <span>{getFileDate({ lastModified: entry.lastModified })}</span>
+        </div>
+      </div>
+      <div className="files-page-card-actions">
+        <Menu shadow="md" position="bottom-end" withinPortal>
+          <Menu.Target>
+            <ActionIcon
+              size="sm"
+              onClick={(e) => e.stopPropagation()}
+              aria-label={t("filesPage.fileMenu", "File actions")}
+            >
+              <MoreVertIcon fontSize="small" />
+            </ActionIcon>
+          </Menu.Target>
+          <Menu.Dropdown>
+            <Menu.Item
+              leftSection={<OpenInNewIcon fontSize="small" />}
+              onClick={(e) => {
+                e.stopPropagation();
+                onOpen();
+              }}
+            >
+              {t("filesPage.addToWorkspace", "Add to workspace")}
+            </Menu.Item>
+          </Menu.Dropdown>
+        </Menu>
+      </div>
+    </div>
+  );
+}
+
+/** List-view sibling of {@link DiskFileCard}; same single affordance. */
+function DiskFileRow({
+  entry,
+  onOpen,
+}: {
+  entry: DiskFileEntry;
+  onOpen: () => void;
+}) {
+  const { t } = useTranslation();
+  const thumbnail = useDiskThumbnail(entry);
+  const ext = entry.name.includes(".")
+    ? entry.name.split(".").pop()!.toUpperCase()
+    : "";
+  return (
+    <div
+      role="row"
+      tabIndex={0}
+      className="files-page-list-row"
+      onDoubleClick={onOpen}
+      onKeyDown={(e) => {
+        if (e.key === "Enter") onOpen();
+      }}
+      title={entry.path}
+    >
+      <span aria-hidden="true" />
+      <span
+        role="gridcell"
+        style={{
+          display: "flex",
+          alignItems: "center",
+          gap: "0.5rem",
+          minWidth: 0,
+        }}
+      >
+        {thumbnail ? (
+          <img
+            src={thumbnail}
+            alt=""
+            draggable={false}
+            style={{
+              width: "1.5rem",
+              height: "1.5rem",
+              objectFit: "cover",
+              borderRadius: "0.25rem",
+            }}
+          />
+        ) : ext === "PDF" ? (
+          <PictureAsPdfIcon fontSize="small" />
+        ) : (
+          <InsertDriveFileIcon fontSize="small" />
+        )}
+        <span
+          style={{
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap",
+          }}
+          title={entry.name}
+        >
+          {entry.name}
+        </span>
+        <FileOriginBadge
+          origin="local"
+          tooltip={t(
+            "filesPage.origin.diskHint",
+            "A file in the mounted folder on your disk",
+          )}
+          compact
+        />
+      </span>
+      <span role="gridcell">{ext || t("filesPage.file", "File")}</span>
+      <span role="gridcell">{formatFileSize(entry.sizeBytes)}</span>
+      <span role="gridcell">
+        {getFileDate({ lastModified: entry.lastModified })}
+      </span>
+      <span role="gridcell">
+        <Menu shadow="md" position="bottom-end" withinPortal>
+          <Menu.Target>
+            <ActionIcon
+              variant="tertiary"
+              size="sm"
+              onClick={(e) => e.stopPropagation()}
+              aria-label={t("filesPage.fileMenu", "File actions")}
+            >
+              <MoreVertIcon fontSize="small" />
+            </ActionIcon>
+          </Menu.Target>
+          <Menu.Dropdown>
+            <Menu.Item
+              leftSection={<OpenInNewIcon fontSize="small" />}
+              onClick={onOpen}
+            >
+              {t("filesPage.addToWorkspace", "Add to workspace")}
+            </Menu.Item>
+          </Menu.Dropdown>
+        </Menu>
+      </span>
+    </div>
+  );
+}

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

@@ -10,8 +10,10 @@ import { useLocation, useNavigate } from "react-router-dom";
 import {
   Drawer,
   Group,
+  Menu,
   MultiSelect,
   Select,
+  Text,
   TextInput,
   Tooltip,
 } from "@mantine/core";
@@ -32,6 +34,9 @@ import OpenInNewIcon from "@mui/icons-material/OpenInNew";
 import InfoOutlinedIcon from "@mui/icons-material/InfoOutlined";
 import CloudUploadIcon from "@mui/icons-material/CloudUpload";
 import KeyboardArrowRightIcon from "@mui/icons-material/KeyboardArrowRight";
+import ArrowDropDownIcon from "@mui/icons-material/ArrowDropDown";
+import DriveFolderUploadIcon from "@mui/icons-material/DriveFolderUpload";
+import CloudIcon from "@mui/icons-material/Cloud";
 import RefreshIcon from "@mui/icons-material/Refresh";
 import { FilesToolbarBulkMenu } from "@app/components/filesPage/FilesToolbarBulkMenu";
 import { FilesToolbarCount } from "@app/components/filesPage/FilesToolbarCount";
@@ -45,6 +50,7 @@ import { useFolders } from "@app/contexts/FolderContext";
 import { useFileActions } from "@app/contexts/file/fileHooks";
 import { useAllFiles } from "@app/contexts/FileContext";
 import { useFileHandler } from "@app/hooks/useFileHandler";
+import { useServerFolderBlock } from "@app/hooks/useServerFolderBlock";
 import {
   useNavigationActions,
   useNavigationGuard,
@@ -60,7 +66,7 @@ import { getFileOrigin } from "@app/components/filesPage/fileOrigin";
 
 import { FileId } from "@app/types/file";
 import { StirlingFileStub } from "@app/types/fileContext";
-import { FolderId, ROOT_FOLDER_ID } from "@app/types/folder";
+import { FolderId, ROOT_FOLDER_ID, folderKind } from "@app/types/folder";
 
 import { FileGrid, FilesPageEntry } from "@app/components/filesPage/FileGrid";
 import SuperSearch from "@app/components/shared/superSearch/SuperSearch";
@@ -69,6 +75,20 @@ import { FileDetailsPanel } from "@app/components/filesPage/FileDetailsPanel";
 import BulkUploadToServerModal from "@app/components/shared/BulkUploadToServerModal";
 import MobileUploadModal from "@app/components/shared/MobileUploadModal";
 import { useAppConfig } from "@app/contexts/AppConfigContext";
+import { canPickDirectory } from "@app/services/directoryPicker";
+import {
+  diskFolderId,
+  isDiskFolderId,
+  pickFolderColor,
+} from "@app/types/folder";
+import { useNewFolderFlow } from "@app/hooks/useNewFolderFlow";
+import { writeIntoMount } from "@app/services/mountWrites";
+import {
+  canListDirectory,
+  listDirectory,
+  readDiskFile,
+  type DiskFileEntry,
+} from "@app/services/localFolderContents";
 import { useIsMobile } from "@app/hooks/useIsMobile";
 import { MoveToFolderDialog } from "@app/components/filesPage/MoveToFolderDialog";
 import { FolderNameDialog } from "@app/components/filesPage/FolderNameDialog";
@@ -201,6 +221,7 @@ export default function FileManagerView() {
   );
 
   const setCurrentFolderId = folders.setCurrentFolderId;
+  const resolveDiskFolder = folders.resolveDiskFolder;
   const foldersById = folders.foldersById;
   const currentFolderId = folders.currentFolderId;
 
@@ -212,10 +233,13 @@ export default function FileManagerView() {
       setCurrentFolderId(ROOT_FOLDER_ID);
     } else if (foldersById.has(param as FolderId)) {
       setCurrentFolderId(param as FolderId);
+    } else if (isDiskFolderId(param) && resolveDiskFolder(param as FolderId)) {
+      // A mount subdirectory deep link: rebuilt from the id, mapped next render.
+      setCurrentFolderId(param as FolderId);
     } else {
       setCurrentFolderId(ROOT_FOLDER_ID);
     }
-  }, [location.pathname, foldersById, setCurrentFolderId]);
+  }, [location.pathname, foldersById, setCurrentFolderId, resolveDiskFolder]);
 
   // Bounce off any share-related tab when sharing isn't enabled.
   useEffect(() => {
@@ -275,6 +299,8 @@ export default function FileManagerView() {
     }
     const lc = search.toLowerCase();
     const matched = folders.folders.filter((f) => {
+      // The Cloud tab is the server's view: browser folders and mounts aren't on it.
+      if (currentTab === "cloud" && folderKind(f) !== "server") return false;
       if (search) {
         // Subtree-wide name match; exclude the current folder itself.
         return (
@@ -296,10 +322,11 @@ export default function FileManagerView() {
     // Tab overrides folder navigation for Local/Recent/Shared.
     switch (currentTab) {
       case "local":
-        // Local = files with no server copy. folderId is forced null on this
-        // path (cf. file.ts comment), but we check remoteStorageId too so
-        // stale local-folder rows from a pre-pivot DB don't slip through.
-        return allFiles.filter((f) => f.remoteStorageId == null);
+        // Both halves: a local file inside a browser folder belongs to that folder,
+        // not here as well.
+        return allFiles.filter(
+          (f) => f.remoteStorageId == null && (f.folderId ?? null) === null,
+        );
       case "cloud":
         // Cloud bucket; search widens to subtree, else direct-folder match.
         return allFiles.filter((f) => {
@@ -426,12 +453,141 @@ export default function FileManagerView() {
     [foldersById],
   );
 
+  const currentFolder = currentFolderId
+    ? folders.foldersById.get(currentFolderId)
+    : undefined;
+  const currentLocalDirectory =
+    currentFolder && folderKind(currentFolder) === "local"
+      ? currentFolder.directory
+      : undefined;
+  const { setError: setFolderError, registerDiskSubfolders } = folders;
+  const [diskEntries, setDiskEntries] = useState<DiskFileEntry[]>([]);
+  const [diskLoading, setDiskLoading] = useState(false);
+  // Bumped when this view writes into the directory, so the listing re-reads.
+  const [diskRefreshTick, setDiskRefreshTick] = useState(0);
+  useEffect(() => {
+    if (!currentLocalDirectory || !canListDirectory) {
+      setDiskEntries([]);
+      // Leaving a mount mid-listing cancels the in-flight reset, so clear the
+      // flag here or the skeleton covers every folder for the rest of the session.
+      setDiskLoading(false);
+      return;
+    }
+    let cancelled = false;
+    setDiskLoading(true);
+    listDirectory(currentLocalDirectory)
+      .then((listed) => {
+        if (cancelled) return;
+        setDiskEntries(listed?.files ?? []);
+        if (currentFolderId !== null) {
+          registerDiskSubfolders(
+            currentFolderId,
+            (listed?.directories ?? []).map((dir) => ({
+              id: diskFolderId(dir.path),
+              kind: "local" as const,
+              name: dir.name,
+              parentFolderId: currentFolderId,
+              directory: dir.path,
+              color: pickFolderColor(dir.name),
+              createdAt: 0,
+              updatedAt: 0,
+            })),
+          );
+        }
+      })
+      .catch((err) => {
+        console.warn("[FileManagerView] disk listing failed", err);
+        if (!cancelled) {
+          setDiskEntries([]);
+          setFolderError(
+            err instanceof Error
+              ? t("filesPage.error.readFolderFailedDetail", {
+                  message: err.message,
+                  defaultValue: `Could not read the folder: ${err.message}`,
+                })
+              : t(
+                  "filesPage.error.readFolderFailed",
+                  "Could not read the folder.",
+                ),
+          );
+        }
+      })
+      .finally(() => {
+        if (!cancelled) setDiskLoading(false);
+      });
+    return () => {
+      cancelled = true;
+    };
+    // The stable setter, not the context: its identity changes on every folder
+    // mutation, including the setError above, so a failing listing would re-trigger.
+  }, [
+    currentLocalDirectory,
+    currentFolderId,
+    registerDiskSubfolders,
+    setFolderError,
+    diskRefreshTick,
+    t,
+  ]);
+
+  const openDiskFile = useCallback(
+    async (entry: DiskFileEntry) => {
+      try {
+        const file = await readDiskFile(entry);
+        if (!file) return;
+        clearFilesPageReturnRoute();
+        await addFiles([file], { selectFiles: true });
+        navActions.setWorkbench("viewer");
+        navigate("/");
+      } catch (err) {
+        folders.setError(
+          err instanceof Error
+            ? t("filesPage.error.openDiskFileFailedDetail", {
+                name: entry.name,
+                message: err.message,
+                defaultValue: `Could not open ${entry.name}: ${err.message}`,
+              })
+            : t("filesPage.error.openDiskFileFailed", {
+                name: entry.name,
+                defaultValue: `Could not open ${entry.name}.`,
+              }),
+        );
+      }
+    },
+    [addFiles, navActions, navigate, folders, t],
+  );
+
   const entries = useMemo<FilesPageEntry[]>(() => {
     // When searching, items may come from anywhere in the subtree, so we
     // expose a "parentPath" subtitle whenever the item's parent differs from
     // currentFolderId. When no search is active, every item is in the
     // current folder by definition and the subtitle is suppressed.
     const inSearch = search.length > 0;
+    // Inside a mount the listing is the directory; storage rows don't apply.
+    if (currentLocalDirectory) {
+      const needle = search.toLowerCase();
+      const compare: Record<
+        string,
+        (a: DiskFileEntry, b: DiskFileEntry) => number
+      > = {
+        "name-asc": (a, b) => a.name.localeCompare(b.name),
+        "name-desc": (a, b) => b.name.localeCompare(a.name),
+        "size-asc": (a, b) => a.sizeBytes - b.sizeBytes,
+        "size-desc": (a, b) => b.sizeBytes - a.sizeBytes,
+        "modified-asc": (a, b) => a.lastModified - b.lastModified,
+        "modified-desc": (a, b) => b.lastModified - a.lastModified,
+      };
+      return [
+        ...visibleFolders.map<FilesPageEntry>((folder) => ({
+          kind: "folder",
+          folder,
+          folderFileCount: 0,
+        })),
+        ...diskEntries
+          .filter((disk) => !needle || disk.name.toLowerCase().includes(needle))
+          .sort(compare[filesPage.sortMode] ?? compare["modified-desc"]!)
+          .map<FilesPageEntry>((disk) => ({ kind: "diskFile", disk })),
+      ];
+    }
     return [
       ...visibleFolders.map<FilesPageEntry>((folder) => ({
         kind: "folder",
@@ -457,6 +613,9 @@ export default function FileManagerView() {
     filesPage.fileCountsByFolder,
     search,
     currentFolderId,
+    currentLocalDirectory,
+    diskEntries,
+    filesPage.sortMode,
     pathForFolderId,
   ]);
 
@@ -531,28 +690,46 @@ export default function FileManagerView() {
       // state - otherwise the file pops up the next time the user navigates
       // to /viewer or /tools, which reads as "auto-opened" and surprised
       // people every time. The grid will repaint via refresh() below.
+      // Files uploaded while standing in a folder belong in that folder.
+      const target =
+        currentTab === "all" || currentTab === "cloud" ? currentFolderId : null;
+      const targetFolder = target ? folders.foldersById.get(target) : undefined;
+      if (targetFolder && folderKind(targetFolder) === "local") {
+        const { failedCount } = await writeIntoMount(
+          targetFolder.directory,
+          files.map((file) => ({ name: file.name, bytes: async () => file })),
+        );
+        if (failedCount > 0) {
+          folders.setError(
+            t("filesPage.moveIntoMountFailed", {
+              count: failedCount,
+              defaultValue:
+                "{{count}} file(s) could not be written into the folder.",
+            }),
+          );
+        }
+        setDiskRefreshTick((tick) => tick + 1);
+        return;
+      }
+      // Everywhere else membership is set with the stub rather than by a move that
+      // could fail after. For a server folder it stays local until the save lands.
       const added = await addFiles(files, {
         selectFiles: false,
         skipWorkspaceDispatch: true,
+        ...(target ? { folderId: target as string } : {}),
       });
       const fileIds = added.map((f) => f.fileId);
-      const target = currentFolderId;
-      // Uploaded files land in Local (folderId stays null).
       if (
         target !== null &&
         fileIds.length > 0 &&
-        (currentTab === "all" || currentTab === "cloud")
+        targetFolder &&
+        folderKind(targetFolder) === "server"
       ) {
-        folders.setError(
-          t(
-            "filesPage.uploadedToLocal",
-            "Uploaded files start in Local. Use 'Save to cloud' to put them in a folder.",
-          ),
-        );
+        await moveFilesTo(fileIds, target);
       }
       await refresh();
     },
-    [addFiles, currentFolderId, currentTab, folders, refresh, t],
+    [addFiles, currentFolderId, currentTab, folders, moveFilesTo, refresh, t],
   );
 
   const onFileInputChange = useCallback(
@@ -913,20 +1090,18 @@ export default function FileManagerView() {
     [selectedFiles, fileMap],
   );
 
+  // Per-destination availability for the New-folder menu; the reason renders as the
+  // disabled item's caption.
+  const serverFolderDisabledReason = useServerFolderBlock() ?? undefined;
+
+  const { addLocalFolder, createFolderHere, createFolderHereBlockedReason } =
+    useNewFolderFlow();
+
   // null = New folder actionable; string = disabled tooltip reason.
   const newFolderDisabledReason: string | null = useMemo(() => {
-    // Guests can't use cloud folders at all - say so before any tab/storage
-    // hint, since switching tabs wouldn't help them.
-    if (signInRequiredReason) {
-      return signInRequiredReason;
-    }
-    if (currentTab === "local") {
-      return t(
-        "filesPage.localFoldersUnavailable",
-        "Folders are cloud-only - save a file to the cloud to organise it.",
-      );
-    }
+    // Only All/Cloud render folders, so creating one elsewhere would look inert.
     if (
+      currentTab === "local" ||
       currentTab === "recent" ||
       currentTab === "shared" ||
       currentTab === "sharedByMe"
@@ -936,14 +1111,32 @@ export default function FileManagerView() {
         "Switch to All or Cloud to create folders.",
       );
     }
-    if (!folders.serverReachable) {
-      return t(
-        "filesPage.newFolderStorageDisabled",
-        "Server folder storage isn't enabled. Ask your admin to turn it on.",
-      );
+    // A subfolder inherits kind server, so the blockers gate the button rather
+    // than letting the dialog open and fail at submit.
+    if (
+      currentFolder &&
+      folderKind(currentFolder) === "server" &&
+      serverFolderDisabledReason
+    ) {
+      return serverFolderDisabledReason;
+    }
+    // The web root creates on the server or not at all.
+    if (
+      folders.currentFolderId === null &&
+      !canPickDirectory &&
+      serverFolderDisabledReason
+    ) {
+      return serverFolderDisabledReason;
     }
     return null;
-  }, [signInRequiredReason, currentTab, folders.serverReachable, t]);
+  }, [
+    currentTab,
+    currentLocalDirectory,
+    currentFolder,
+    folders.currentFolderId,
+    serverFolderDisabledReason,
+    t,
+  ]);
 
   return (
     <div className="files-page" ref={dropZoneRef}>
@@ -977,6 +1170,10 @@ export default function FileManagerView() {
           const handleRefresh = async () => {
             setRefreshing(true);
             try {
+              // In a mount, refresh means the directory: the listing only re-reads when told.
+              if (currentLocalDirectory) {
+                setDiskRefreshTick((tick) => tick + 1);
+              }
               // pullFromServer bumps the folder revision, which the
               // FolderProvider's effect reacts to by re-running refresh() -
               // no need to await folders.refresh() manually.
@@ -1045,15 +1242,69 @@ export default function FileManagerView() {
                       </Button>
                     </span>
                   </Tooltip>
-                ) : (
+                ) : folders.currentFolderId !== null || !canPickDirectory ? (
+                  // Nothing to choose: a subfolder inherits its parent's kind, and on
+                  // the web everything lives on the server. Straight to the dialog.
                   <Button
                     variant="secondary"
                     size="sm"
                     leftSection={<CreateNewFolderIcon fontSize="small" />}
-                    onClick={() => openNewFolderDialog()}
+                    onClick={() =>
+                      folders.currentFolderId !== null
+                        ? openNewFolderDialog()
+                        : openNewFolderDialog(null, "server")
+                    }
                   >
                     {t("filesPage.newFolder", "New folder")}
                   </Button>
+                ) : (
+                  // Desktop root: two peer destinations, so the button is the menu.
+                  <Menu shadow="md" position="bottom-end" withinPortal>
+                    <Menu.Target>
+                      <Button
+                        variant="secondary"
+                        size="sm"
+                        leftSection={<CreateNewFolderIcon fontSize="small" />}
+                        rightSection={<ArrowDropDownIcon fontSize="small" />}
+                      >
+                        {t("filesPage.newFolder", "New folder")}
+                      </Button>
+                    </Menu.Target>
+                    <Menu.Dropdown>
+                      <Menu.Item
+                        leftSection={
+                          <DriveFolderUploadIcon
+                            fontSize="small"
+                            style={{ marginRight: "0.3rem" }}
+                          />
+                        }
+                        onClick={() => void addLocalFolder()}
+                      >
+                        {t(
+                          "filesPage.newFolderMenu.addExisting",
+                          "Add local folder",
+                        )}
+                      </Menu.Item>
+                      <Menu.Item
+                        className="files-page-new-folder-option"
+                        leftSection={<CloudIcon fontSize="small" />}
+                        disabled={Boolean(serverFolderDisabledReason)}
+                        onClick={() => openNewFolderDialog(null, "server")}
+                      >
+                        {t(
+                          "filesPage.newFolderMenu.server",
+                          "New folder on the server",
+                        )}
+                        <Text size="xs" c="dimmed">
+                          {serverFolderDisabledReason ??
+                            t(
+                              "filesPage.newFolderMenu.serverHint",
+                              "Synced to your account, available wherever you sign in.",
+                            )}
+                        </Text>
+                      </Menu.Item>
+                    </Menu.Dropdown>
+                  </Menu>
                 )}
                 <Button
                   size="sm"
@@ -1647,7 +1898,7 @@ export default function FileManagerView() {
           >
             <FileGrid
               entries={entries}
-              loading={loading}
+              loading={loading || diskLoading}
               currentTab={currentTab}
               searchActive={search.trim().length > 0}
               serverReachable={folders.serverReachable}
@@ -1659,6 +1910,7 @@ export default function FileManagerView() {
               onSelectFile={handleSelectFile}
               onSetSelection={setSelectedFileIds}
               onOpenFolder={handleOpenFolder}
+              onOpenDiskFile={(entry) => void openDiskFile(entry)}
               onOpenFile={handleOpenFile}
               onMoveFiles={moveFilesTo}
               onMoveFolder={moveFolderTo}
@@ -1692,8 +1944,12 @@ export default function FileManagerView() {
               // (disabled tooltips, native file picker, dialog) is
               // identical regardless of where the user clicks from.
               onEmptyUpload={() => fileInputRef.current?.click()}
-              onEmptyCreateFolder={() => openNewFolderDialog()}
-              newFolderDisabledReason={newFolderDisabledReason}
+              onEmptyCreateFolder={createFolderHere}
+              // A single-click shortcut, so it also blocks where it has nothing safe
+              // to do, unlike the header button whose menu still offers the choices.
+              newFolderDisabledReason={
+                newFolderDisabledReason ?? createFolderHereBlockedReason
+              }
             />
             {isDraggingExternal && (
               <div className="files-page-drop-overlay" aria-live="polite">
@@ -1704,16 +1960,21 @@ export default function FileManagerView() {
                   {t("filesPage.dropOverlay", "Drop files to upload")}
                 </span>
                 <span className="files-page-drop-overlay-sub">
-                  {/* Behavior contract: per handleNativeUpload above, all
-                      newly-uploaded files start in Local (folderId stays
-                      null) regardless of the current folder view. Saying
-                      "will land in {folder}" was a lie; tell the truth
-                      so the user reaches for Save-to-cloud / Move-to when
-                      they actually want a folder placement. */}
-                  {t(
-                    "filesPage.dropOverlaySub",
-                    "Files start in Local. Use 'Move to' or 'Save to cloud' to organise them into a folder.",
-                  )}
+                  {/* Behavior contract: per handleNativeUpload above, files
+                      dropped inside a folder on the All/Cloud views are
+                      placed into it — a mount takes them onto the disk
+                      itself. Other tabs land drops in Local, so the copy
+                      must match. */}
+                  {(currentTab === "all" || currentTab === "cloud") &&
+                  currentFolderId !== null
+                    ? t(
+                        "filesPage.dropOverlaySubFolder",
+                        "They'll be added to this folder.",
+                      )
+                    : t(
+                        "filesPage.dropOverlaySub",
+                        "Files land in Local. Organise them into folders any time.",
+                      )}
                 </span>
               </div>
             )}
@@ -1774,7 +2035,14 @@ export default function FileManagerView() {
       <MoveToFolderDialog
         opened={moveDialog.open}
         onClose={closeMoveDialog}
-        folders={folders.folders}
+        // Files can go anywhere, but a folder moves only within its own kind and
+        // never into a mount - a directory's subfolders are the filesystem's.
+        folders={folders.folders.filter((candidate) => {
+          if (!moveDialog.folderId) return true;
+          if (folderKind(candidate) === "local") return false;
+          const moving = folders.foldersById.get(moveDialog.folderId);
+          return moving ? folderKind(candidate) === folderKind(moving) : true;
+        })}
         initialFolderId={moveDialog.initial}
         disabledFolderId={moveDialog.folderId}
         onConfirm={async (target) => {

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

@@ -11,6 +11,7 @@ interface FileOriginBadgeProps {
   origin: FileOrigin;
   /** Compact (icon-only) vs full (icon + text). */
   compact?: boolean;
+  tooltip?: string;
 }
 
 const styles = {
@@ -44,6 +45,7 @@ const styles = {
 export function FileOriginBadge({
   origin,
   compact = false,
+  tooltip,
 }: FileOriginBadgeProps) {
   const { t } = useTranslation();
 
@@ -88,7 +90,7 @@ export function FileOriginBadge({
   );
 
   return (
-    <Tooltip label={config.tooltip} withinPortal>
+    <Tooltip label={tooltip ?? config.tooltip} withinPortal>
       {badge}
     </Tooltip>
   );

frontend/editor/src/core/components/filesPage/FilesPage.css

@@ -582,8 +582,13 @@
   position: absolute;
   bottom: 0.4rem;
   left: 0.4rem;
+  /* The overlay itself stays transparent to the card's clicks and drags, but
+     the badge inside must catch hover or its tooltip can never open. */
   pointer-events: none;
 }
+.files-page-card-origin > * {
+  pointer-events: auto;
+}
 
 /* "Open" badge - file is currently loaded in the active workspace.
    Solid pill with white text so it reads against any thumbnail
@@ -1494,3 +1499,14 @@
     transform: none;
   }
 }
+
+/* A disabled destination still has to be read - its caption carries the reason - and
+   Mantine's disabled colour drops below comfortable contrast in dark mode. Selector
+   stands on the item's own class because the dropdown renders in a portal. */
+.files-page-new-folder-option[data-disabled] {
+  color: var(--c-text-muted) !important;
+  opacity: 1;
+}
+.files-page-new-folder-option[data-disabled] .mantine-Text-root {
+  color: var(--c-text-subtle) !important;
+}

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

@@ -16,6 +16,7 @@ import { useFolders } from "@app/contexts/FolderContext";
 import { FileId } from "@app/types/file";
 import {
   FolderId,
+  folderKind,
   FolderRecord,
   FolderTreeNode,
   ROOT_FOLDER_ID,
@@ -260,6 +261,12 @@ function TreeNodeRow({
 }: TreeNodeRowProps) {
   const { t } = useTranslation();
   const { serverReachable, setError } = useFolders();
+  // Server folders need the server; a virtual folder is browser-owned and a
+  // local one is managed by its directory, so its edit items disable with a
+  // kind-specific hint instead of a wrong "offline" excuse.
+  const kind = folderKind(node.folder);
+  const editsDisabled =
+    kind === "local" || (kind === "server" && !serverReachable);
   const { currentTab } = useFilesPage();
   const offlineHint = t(
     "filesPage.offlineNoFolderEdits",
@@ -433,8 +440,17 @@ function TreeNodeRow({
                 e.stopPropagation();
                 onRenameFolder(node.folder);
               }}
-              disabled={!serverReachable}
-              title={!serverReachable ? offlineHint : undefined}
+              disabled={editsDisabled}
+              title={
+                kind === "local"
+                  ? t(
+                      "filesPage.localFolderManagedByDisk",
+                      "This folder is managed by its directory on disk.",
+                    )
+                  : editsDisabled
+                    ? offlineHint
+                    : undefined
+              }
             >
               {t("filesPage.treeMenu.rename", "Rename")}
             </Menu.Item>
@@ -444,24 +460,48 @@ function TreeNodeRow({
                 e.stopPropagation();
                 onRequestNewFolder(node.folder.id);
               }}
-              disabled={!serverReachable}
-              title={!serverReachable ? offlineHint : undefined}
+              disabled={editsDisabled}
+              title={
+                kind === "local"
+                  ? t(
+                      "filesPage.localFolderManagedByDisk",
+                      "This folder is managed by its directory on disk.",
+                    )
+                  : editsDisabled
+                    ? offlineHint
+                    : undefined
+              }
             >
               {t("filesPage.treeMenu.newSubfolder", "New subfolder")}
             </Menu.Item>
             <Menu.Divider />
-            <Menu.Item
-              color="red"
-              leftSection={<DeleteOutlineIcon fontSize="small" />}
-              onClick={(e) => {
-                e.stopPropagation();
-                onDeleteFolder(node.folder);
-              }}
-              disabled={!serverReachable}
-              title={!serverReachable ? offlineHint : undefined}
-            >
-              {t("filesPage.treeMenu.delete", "Delete folder")}
-            </Menu.Item>
+            {/* Every kind can be removed except a mount's subdirectory, which
+                is the disk's — the app never deletes directories. A mount
+                root's removal deletes the record and nothing on disk, so only
+                the server kind's reachability gate applies. */}
+            {(kind !== "local" || node.folder.parentFolderId === null) && (
+              <Menu.Item
+                color="red"
+                leftSection={<DeleteOutlineIcon fontSize="small" />}
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onDeleteFolder(node.folder);
+                }}
+                disabled={kind === "server" && !serverReachable}
+                title={
+                  kind === "server" && !serverReachable
+                    ? offlineHint
+                    : undefined
+                }
+              >
+                {kind === "local"
+                  ? t(
+                      "filesPage.removeLocalFolder",
+                      "Remove (files stay on disk)",
+                    )
+                  : t("filesPage.treeMenu.delete", "Delete folder")}
+              </Menu.Item>
+            )}
           </Menu.Dropdown>
         </Menu>
       </div>

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

@@ -267,6 +267,8 @@ function FileContextInner({
         skipWorkspaceDispatch?: boolean;
         skipUploadTracking?: boolean;
         derivedFromTool?: boolean;
+        /** Folder every added file is born into (see AddFileOptions). */
+        folderId?: string;
       },
     ): Promise<StirlingFile[]> => {
       const stirlingFiles = await addFiles(

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

@@ -13,8 +13,15 @@ import { useTranslation } from "react-i18next";
 
 import { FileId } from "@app/types/file";
 import { StirlingFileStub } from "@app/types/fileContext";
-import { FolderId, FolderRecord, ROOT_FOLDER_ID } from "@app/types/folder";
+import {
+  FolderId,
+  FolderKind,
+  FolderRecord,
+  ROOT_FOLDER_ID,
+  folderKind,
+} from "@app/types/folder";
 import { fileStorage } from "@app/services/fileStorage";
+import { writeIntoMount } from "@app/services/mountWrites";
 import { folderSyncService } from "@app/services/folderSyncService";
 import { uploadHistoryChain } from "@app/services/serverStorageUpload";
 import { reconcileServerFiles } from "@app/services/fileSyncService";
@@ -59,6 +66,8 @@ export type FilesPageTab =
 export interface FolderNameDialogState {
   mode: "new" | "rename" | null;
   parentId?: FolderId | null;
+  /** For a root-level create: the kind the caller chose (menu, not dialog). */
+  kind?: FolderKind;
   folder?: FolderRecord;
 }
 
@@ -102,7 +111,7 @@ interface FilesPageContextValue {
 
   // Dialog state
   folderNameDialog: FolderNameDialogState;
-  openNewFolderDialog: (parentId?: FolderId | null) => void;
+  openNewFolderDialog: (parentId?: FolderId | null, kind?: FolderKind) => void;
   openRenameFolderDialog: (folder: FolderRecord) => void;
   closeFolderNameDialog: () => void;
   submitFolderName: (name: string) => Promise<void>;
@@ -243,8 +252,11 @@ export function FilesPageProvider({ children }: { children: React.ReactNode }) {
     useState<FolderNameDialogState>({ mode: null });
 
   const openNewFolderDialog = useCallback(
-    (parentId: FolderId | null = folders.currentFolderId) => {
-      setFolderNameDialog({ mode: "new", parentId });
+    (
+      parentId: FolderId | null = folders.currentFolderId,
+      kind?: FolderKind,
+    ) => {
+      setFolderNameDialog({ mode: "new", parentId, kind });
     },
     [folders.currentFolderId],
   );
@@ -260,9 +272,11 @@ export function FilesPageProvider({ children }: { children: React.ReactNode }) {
   const submitFolderName = useCallback(
     async (name: string) => {
       if (folderNameDialog.mode === "new") {
+        // Chosen before the dialog opened, and only used at the root.
         await folders.createFolder(
           name,
           folderNameDialog.parentId ?? folders.currentFolderId,
+          folderNameDialog.kind,
         );
       } else if (
         folderNameDialog.mode === "rename" &&
@@ -297,13 +311,89 @@ export function FilesPageProvider({ children }: { children: React.ReactNode }) {
   const moveFilesTo = useCallback(
     async (fileIds: FileId[], folderId: FolderId | null) => {
       if (fileIds.length === 0) return;
-      const stubs = fileIds
-        .map((id) => fileMap.get(id))
-        .filter((s): s is StirlingFileStub => Boolean(s));
+      // fileMap is a render-time snapshot, so a file created moments ago is not in
+      // it yet. Storage is the truth, and falling back keeps it in the move.
+      const fetched = await Promise.all(
+        fileIds.map(
+          (id) => fileMap.get(id) ?? fileStorage.getStirlingFileStub(id),
+        ),
+      );
+      const stubs = fetched.filter((s): s is StirlingFileStub => Boolean(s));
       const localOnly = stubs.filter((s) => s.remoteStorageId == null);
       // Cloud list is mutated below with newly-promoted local files.
       const cloudFiles = stubs.filter((s) => s.remoteStorageId != null);
 
+      const targetFolder =
+        folderId === null ? null : folders.foldersById.get(folderId);
+      const targetKind = targetFolder ? folderKind(targetFolder) : null;
+
+      if (targetKind === "local") {
+        // In a mount means on the disk: write each file into the directory, then retire
+        // the app-side copy once the bytes verifiably landed.
+        const { written, failedCount } = await writeIntoMount(
+          targetFolder?.directory,
+          localOnly.map((stub) => ({
+            name: stub.name,
+            bytes: () => fileStorage.getStirlingFile(stub.id),
+          })),
+        );
+        const movedIds = localOnly
+          .filter((_, i) => written[i])
+          .map((stub) => stub.id);
+        if (movedIds.length > 0) {
+          // Superseded versions go too, or their bytes sit in storage unseen.
+          const orphans = await fileStorage.orphanedAncestorIds(movedIds);
+          await fileActions.removeFiles([...movedIds, ...orphans], true);
+        }
+        // One error slot, two possible failures: report both.
+        const notices: string[] = [];
+        if (failedCount > 0) {
+          notices.push(
+            t("filesPage.moveIntoMountFailed", {
+              count: failedCount,
+              defaultValue:
+                "{{count}} file(s) could not be written into the folder.",
+            }),
+          );
+        }
+        if (cloudFiles.length > 0) {
+          notices.push(
+            t("filesPage.moveIntoMountCloudSkipped", {
+              count: cloudFiles.length,
+              defaultValue:
+                "{{count}} server file(s) stayed in your files. They live on the server, not on this disk.",
+            }),
+          );
+        }
+        if (notices.length > 0) {
+          folders.setError(notices.join(" "));
+        }
+        await refresh();
+        return;
+      }
+
+      if (targetKind === "virtual") {
+        // A browser-owned folder cannot hold server files: the next sync would snap
+        // them back, so they are left where they are and reported.
+        if (cloudFiles.length > 0) {
+          folders.setError(
+            t(
+              "filesPage.moveIntoVirtualCloudSkipped",
+              "{{count}} server file(s) were left in place. Server files can't live in browser-only folders.",
+              { count: cloudFiles.length },
+            ),
+          );
+        }
+        if (localOnly.length > 0) {
+          await indexedDB.moveFilesToFolder(
+            localOnly.map((s) => s.id),
+            folderId,
+          );
+        }
+        await refresh();
+        return;
+      }
+
       if (folderId !== null && localOnly.length > 0) {
         // Per-file uploadHistoryChain so each gets its own remoteStorageId.
         try {
@@ -379,7 +469,17 @@ export function FilesPageProvider({ children }: { children: React.ReactNode }) {
         }
       }
 
-      // Local files moving to ROOT need no cloud write.
+      // Local files moving to the root DO need a write when they are leaving a folder —
+      // their membership is a browser-side folderId that nothing above has touched (the
+      // upload branch only runs for a non-null target).
+      if (folderId === null && localOnly.length > 0) {
+        const leaving = localOnly
+          .filter((s) => (s.folderId ?? null) !== null)
+          .map((s) => s.id);
+        if (leaving.length > 0) {
+          await indexedDB.moveFilesToFolder(leaving, null);
+        }
+      }
       await refresh();
     },
     [indexedDB, refresh, fileMap, folders, t, fileActions],
@@ -397,6 +497,22 @@ export function FilesPageProvider({ children }: { children: React.ReactNode }) {
         );
         return;
       }
+      // A subtree is one kind throughout (each kind has its own system of
+      // record), so a cross-kind drop is refused here as a message rather
+      // than surfacing as a thrown error from the context.
+      if (newParentId !== null) {
+        const source = folders.foldersById.get(folderId);
+        const target = folders.foldersById.get(newParentId);
+        if (source && target && folderKind(source) !== folderKind(target)) {
+          folders.setError(
+            t(
+              "filesPage.moveAcrossKindsBlocked",
+              "These folders live in different places, so one can't go inside the other.",
+            ),
+          );
+          return;
+        }
+      }
       await folders.moveFolder(folderId, newParentId);
     },
     [folders, t],
@@ -554,10 +670,29 @@ export function FilesPageProvider({ children }: { children: React.ReactNode }) {
 
   const promptDeleteFolder = useCallback(
     (folder: FolderRecord) => {
+      if (folderKind(folder) === "local") {
+        // Removing a mount destroys nothing — the record goes, the directory and every
+        // file in it stay — so there is nothing to warn about and the delete dialog's
+        // "what about the files?" question would be a scary lie.
+        void folders.deleteFolder(folder.id).catch((err) => {
+          folders.setError(
+            err instanceof Error
+              ? t("filesPage.error.removeFolderFailedDetail", {
+                  message: err.message,
+                  defaultValue: `Could not remove folder: ${err.message}`,
+                })
+              : t(
+                  "filesPage.error.removeFolderFailed",
+                  "Could not remove folder.",
+                ),
+          );
+        });
+        return;
+      }
       const fileCount = filesInSubtree(folder.id).length;
       setDeleteFolderDialog({ folder, fileCount });
     },
-    [filesInSubtree],
+    [filesInSubtree, folders, t],
   );
 
   const deleteFolder = useCallback(

frontend/editor/src/core/contexts/FolderContext.test.tsx

@@ -93,6 +93,26 @@ vi.mock("@app/services/folderStorage", () => ({
   },
 }));
 
+// The virtual store is exercised by its own suite (virtualFolderStorage.test);
+// here it only needs to exist and be empty so the merged load resolves.
+vi.mock("@app/services/virtualFolderStorage", () => ({
+  virtualFolderStorage: {
+    getAllFolders: vi.fn(() => Promise.resolve([])),
+    createFolder: vi.fn(),
+    updateFolder: vi.fn(),
+    moveFolder: vi.fn(),
+    deleteFolder: vi.fn(() => Promise.resolve([])),
+  },
+}));
+
+vi.mock("@app/services/localFolderStorage", () => ({
+  localFolderStorage: {
+    getAllFolders: vi.fn(() => Promise.resolve([])),
+    mountDirectory: vi.fn(),
+    removeFolder: vi.fn(() => Promise.resolve()),
+  },
+}));
+
 vi.mock("@app/contexts/IndexedDBContext", () => ({
   useIndexedDB: () => ({
     clearFolderForFiles: vi.fn().mockResolvedValue(undefined),

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

@@ -26,16 +26,25 @@ import React, {
 } from "react";
 
 import { folderStorage } from "@app/services/folderStorage";
+import { virtualFolderStorage } from "@app/services/virtualFolderStorage";
+import { localFolderStorage } from "@app/services/localFolderStorage";
 import { folderSyncService } from "@app/services/folderSyncService";
 import {
   FolderBreadcrumbEntry,
   FolderId,
+  FolderKind,
   FolderRecord,
   FolderTreeNode,
   ROOT_FOLDER_ID,
   createFolderId,
+  diskFolderId,
+  diskFolderPath,
+  folderKind,
+  isDiskFolderId,
   pickFolderColor,
 } from "@app/types/folder";
+import { directoryKey } from "@app/services/localFolderStorage";
+import { makeDiskDirectory } from "@app/services/localFolderContents";
 import { useIndexedDB } from "@app/contexts/IndexedDBContext";
 import { useAppConfig } from "@app/contexts/AppConfigContext";
 import { useAuth } from "@app/auth/UseSession";
@@ -88,9 +97,11 @@ interface FolderContextValue {
     ok: boolean;
     reason?: "endpoint-missing" | "network" | "server" | "client";
   }>;
+  /** Create a folder. A child takes its parent's kind; only a root create chooses. */
   createFolder: (
     name: string,
     parentFolderId?: FolderId | null,
+    kind?: FolderKind,
   ) => Promise<FolderRecord>;
   renameFolder: (id: FolderId, name: string) => Promise<FolderRecord | null>;
   moveFolder: (
@@ -102,6 +113,14 @@ interface FolderContextValue {
     appearance: { color?: string; icon?: string | null },
   ) => Promise<FolderRecord | null>;
   deleteFolder: (id: FolderId) => Promise<FolderId[]>;
+  /** Idempotent per directory: mounting one already mounted returns its record. */
+  mountLocalFolder: (directory: string, name: string) => Promise<FolderRecord>;
+  registerDiskSubfolders: (parentId: FolderId, records: FolderRecord[]) => void;
+  /**
+   * Rebuild the records behind a disk-subfolder id, for a link arriving before any
+   * listing ran. True when it sits under a known mount and is now registered.
+   */
+  resolveDiskFolder: (id: FolderId) => boolean;
 
   getChildFolderIds: (parentId: FolderId | null) => FolderId[];
   isDescendant: (candidateId: FolderId, ancestorId: FolderId | null) => boolean;
@@ -146,6 +165,25 @@ function buildTree(folders: FolderRecord[]): FolderTreeNode[] {
   return build(ROOT_FOLDER_ID, 0);
 }
 
+/** The record a subdirectory of a mount presents as: kind local, path as id. */
+function diskSubfolderRecord(
+  path: string,
+  name: string,
+  parentFolderId: FolderId,
+): FolderRecord {
+  const now = Date.now();
+  return {
+    id: diskFolderId(path),
+    kind: "local",
+    name,
+    parentFolderId,
+    directory: path,
+    color: pickFolderColor(name),
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
 /** Convert a server-side error to a banner-ready user message. */
 function formatServerError(err: unknown): string {
   if (err && typeof err === "object" && "response" in err) {
@@ -241,7 +279,26 @@ function shouldStrandedReset(
 }
 
 export function FolderProvider({ children }: FolderProviderProps) {
-  const [folders, setFolders] = useState<FolderRecord[]>([]);
+  const [storedFolders, setFolders] = useState<FolderRecord[]>([]);
+  // Never persisted: a directory is its own record, so a listing rebuilds these.
+  const [diskSubfolders, setDiskSubfolders] = useState<
+    Map<FolderId, FolderRecord[]>
+  >(() => new Map());
+  const folders = useMemo(() => {
+    const known = new Set(storedFolders.map((f) => f.id));
+    const synthesized: FolderRecord[] = [];
+    for (const records of diskSubfolders.values()) {
+      for (const record of records) {
+        if (!known.has(record.id)) {
+          known.add(record.id);
+          synthesized.push(record);
+        }
+      }
+    }
+    return synthesized.length
+      ? [...storedFolders, ...synthesized]
+      : storedFolders;
+  }, [storedFolders, diskSubfolders]);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
   // Start `false` so folder-mutation buttons are disabled until the first
@@ -269,9 +326,14 @@ export function FolderProvider({ children }: FolderProviderProps) {
   const refresh = useCallback(async () => {
     setLoading(true);
     try {
-      const all = await folderStorage.getAllFolders();
+      // Three systems of record behind one list; kind says which rules a row follows.
+      const [server, virtual, local] = await Promise.all([
+        folderStorage.getAllFolders(),
+        virtualFolderStorage.getAllFolders(),
+        localFolderStorage.getAllFolders(),
+      ]);
       if (!mountedRef.current) return;
-      setFolders(all);
+      setFolders([...server, ...virtual, ...local]);
     } catch (err) {
       console.error("[FolderContext] cache read failed", err);
       if (mountedRef.current) {
@@ -342,7 +404,11 @@ export function FolderProvider({ children }: FolderProviderProps) {
         console.warn("[FolderContext] cache replace failed", cacheErr);
       }
       if (mountedRef.current) {
-        setFolders(remote);
+        // Server-wins is for server rows: the other kinds have no server copy.
+        setFolders((prev) => [
+          ...remote,
+          ...prev.filter((f) => folderKind(f) !== "server"),
+        ]);
         setServerReachable(true);
         setError(null);
       }
@@ -519,11 +585,65 @@ export function FolderProvider({ children }: FolderProviderProps) {
     [bumpFolderRevision, folders, handleStaleFolder],
   );
 
+  /** The kind of an existing folder, or throw — mutations must never guess. */
+  const requireKind = useCallback(
+    (id: FolderId): FolderKind => {
+      const folder = foldersById.get(id);
+      if (!folder) throw new Error(`Unknown folder: ${id}`);
+      return folderKind(folder);
+    },
+    [foldersById],
+  );
+
   const createFolder = useCallback(
     async (
       name: string,
       parentFolderId: FolderId | null = currentFolderId,
+      kind?: FolderKind,
     ): Promise<FolderRecord> => {
+      // A child's kind is its parent's: one subtree, one system of record.
+      const effectiveKind: FolderKind =
+        parentFolderId !== null
+          ? requireKind(parentFolderId)
+          : (kind ?? "server");
+      if (effectiveKind === "local") {
+        // A mount's subfolder is a directory: make it on disk, present it as a
+        // listing would. Mount roots come from the picker, never here.
+        const parent = parentFolderId ? foldersById.get(parentFolderId) : null;
+        if (!parent?.directory) {
+          throw new Error("Cannot create a folder outside a mounted directory");
+        }
+        const path = await makeDiskDirectory(parent.directory, name);
+        if (path === null) {
+          throw new Error("This build cannot create folders on disk");
+        }
+        const record = diskSubfolderRecord(path, name, parent.id);
+        if (mountedRef.current) {
+          setDiskSubfolders((prev) => {
+            const next = new Map(prev);
+            const siblings = (next.get(parent.id) ?? []).filter(
+              (f) => f.id !== record.id,
+            );
+            next.set(parent.id, [...siblings, record]);
+            return next;
+          });
+          setError(null);
+        }
+        bumpFolderRevision();
+        return record;
+      }
+      if (effectiveKind === "virtual") {
+        const record = await virtualFolderStorage.createFolder(
+          name,
+          parentFolderId,
+        );
+        if (mountedRef.current) {
+          setFolders((prev) => [...prev, record]);
+          setError(null);
+        }
+        bumpFolderRevision();
+        return record;
+      }
       const color = pickFolderColor(name);
       // Client-side id makes server idempotency check safe on retry.
       const id = createFolderId();
@@ -549,11 +669,41 @@ export function FolderProvider({ children }: FolderProviderProps) {
       }
       return result;
     },
-    [currentFolderId, runFolderMutation],
+    [
+      currentFolderId,
+      requireKind,
+      storageBackedByServer,
+      bumpFolderRevision,
+      runFolderMutation,
+    ],
+  );
+
+  /** Apply a mutated non-server record to state; the store already has it. */
+  const applyOwnedRecord = useCallback(
+    (record: FolderRecord | null): FolderRecord | null => {
+      if (record !== null && mountedRef.current) {
+        setFolders((prev) =>
+          prev.map((f) => (f.id === record.id ? record : f)),
+        );
+        setError(null);
+      }
+      bumpFolderRevision();
+      return record;
+    },
+    [bumpFolderRevision],
   );
 
   const renameFolder = useCallback(
     async (id: FolderId, name: string) => {
+      const kind = requireKind(id);
+      if (kind === "local") {
+        throw new Error("A local folder takes its name from its directory");
+      }
+      if (kind === "virtual") {
+        return applyOwnedRecord(
+          await virtualFolderStorage.updateFolder(id, { name }),
+        );
+      }
       return runFolderMutation(
         () => folderSyncService.update(id, { name }),
         async (record) => {
@@ -565,11 +715,23 @@ export function FolderProvider({ children }: FolderProviderProps) {
         id,
       );
     },
-    [runFolderMutation],
+    [applyOwnedRecord, requireKind, runFolderMutation],
   );
 
   const moveFolder = useCallback(
     async (id: FolderId, newParentId: FolderId | null) => {
+      const kind = requireKind(id);
+      if (newParentId !== null && requireKind(newParentId) !== kind) {
+        throw new Error("Folders can only move within their own kind");
+      }
+      if (kind === "local") {
+        throw new Error("A local folder sits where its directory sits");
+      }
+      if (kind === "virtual") {
+        return applyOwnedRecord(
+          await virtualFolderStorage.moveFolder(id, newParentId),
+        );
+      }
       return runFolderMutation(
         () =>
           folderSyncService.update(id, {
@@ -585,7 +747,7 @@ export function FolderProvider({ children }: FolderProviderProps) {
         id,
       );
     },
-    [runFolderMutation],
+    [applyOwnedRecord, requireKind, runFolderMutation],
   );
 
   const updateFolderAppearance = useCallback(
@@ -593,6 +755,23 @@ export function FolderProvider({ children }: FolderProviderProps) {
       id: FolderId,
       appearance: { color?: string; icon?: string | null },
     ) => {
+      const kind = requireKind(id);
+      if (kind === "local") {
+        throw new Error("Local folders cannot be recoloured yet");
+      }
+      if (kind === "virtual") {
+        // Only the fields the picker sent: it sends one key per interaction, and the
+        // store's spread persists an explicit undefined, so passing both would erase
+        // the one the user did not touch. icon: null clears the icon, deliberately.
+        const updates: { color?: string; icon?: string } = {};
+        if (appearance.color !== undefined) updates.color = appearance.color;
+        if (appearance.icon !== undefined) {
+          updates.icon = appearance.icon ?? undefined;
+        }
+        return applyOwnedRecord(
+          await virtualFolderStorage.updateFolder(id, updates),
+        );
+      }
       return runFolderMutation(
         () =>
           folderSyncService.update(id, {
@@ -608,11 +787,50 @@ export function FolderProvider({ children }: FolderProviderProps) {
         id,
       );
     },
-    [runFolderMutation],
+    [applyOwnedRecord, requireKind, runFolderMutation],
   );
 
   const deleteFolder = useCallback(
     async (id: FolderId): Promise<FolderId[]> => {
+      const kind = requireKind(id);
+      if (kind === "local") {
+        if (isDiskFolderId(id)) {
+          throw new Error(
+            "Subfolders of a mounted directory are removed on disk",
+          );
+        }
+        // Removes the record and nothing else; the directory is the user's.
+        await localFolderStorage.removeFolder(id);
+        if (mountedRef.current) {
+          setError(null);
+          setFolders((prev) => prev.filter((f) => f.id !== id));
+          if (currentFolderId === id) {
+            setCurrentFolderId(ROOT_FOLDER_ID);
+          }
+        }
+        bumpFolderRevision();
+        return [id];
+      }
+      if (kind === "virtual") {
+        // Same shape as the server path: subtree delete, strand-reset, detach files.
+        const removed = await virtualFolderStorage.deleteFolder(id);
+        const removedSet = new Set(removed);
+        if (mountedRef.current) {
+          setError(null);
+          setFolders((prev) => prev.filter((f) => !removedSet.has(f.id)));
+          if (
+            currentFolderId &&
+            shouldStrandedReset(currentFolderId, removedSet, folders)
+          ) {
+            setCurrentFolderId(ROOT_FOLDER_ID);
+          }
+        }
+        bumpFolderRevision();
+        await clearFolderForFiles(removed).catch((e) =>
+          console.warn("[FolderContext] virtual folder file cleanup", e),
+        );
+        return removed;
+      }
       // Custom path (not runFolderMutation) because we have two best-effort
       // cleanups to coordinate, and need to reset currentFolderId BEFORE the
       // cleanups so the user isn't stranded inside a tombstone if the cache
@@ -680,9 +898,94 @@ export function FolderProvider({ children }: FolderProviderProps) {
       currentFolderId,
       folders,
       handleStaleFolder,
+      requireKind,
     ],
   );
 
+  const mountLocalFolder = useCallback(
+    async (directory: string, name: string): Promise<FolderRecord> => {
+      const record = await localFolderStorage.mountDirectory(directory, name);
+      if (mountedRef.current) {
+        setError(null);
+        // Idempotent mount can hand back a record that's already listed.
+        setFolders((prev) =>
+          prev.some((f) => f.id === record.id) ? prev : [...prev, record],
+        );
+      }
+      bumpFolderRevision();
+      return record;
+    },
+    [bumpFolderRevision],
+  );
+
+  const registerDiskSubfolders = useCallback(
+    (parentId: FolderId, records: FolderRecord[]) => {
+      setDiskSubfolders((prev) => {
+        const before = prev.get(parentId) ?? [];
+        const same =
+          before.length === records.length &&
+          before.every(
+            (f, i) => f.id === records[i]?.id && f.name === records[i]?.name,
+          );
+        if (same) return prev;
+        const next = new Map(prev);
+        next.set(parentId, records);
+        return next;
+      });
+    },
+    [],
+  );
+
+  const resolveDiskFolder = useCallback(
+    (id: FolderId): boolean => {
+      const path = diskFolderPath(id);
+      if (path === null) return false;
+      const pathKey = directoryKey(path);
+      // The deepest mount containing the path: nested mounts give a shorter chain.
+      let mount: FolderRecord | null = null;
+      let mountKeyLength = -1;
+      for (const folder of storedFolders) {
+        if (folderKind(folder) !== "local" || !folder.directory) continue;
+        const key = directoryKey(folder.directory);
+        const prefix = key.endsWith("/") ? key : `${key}/`;
+        if (pathKey.startsWith(prefix) && key.length > mountKeyLength) {
+          mount = folder;
+          mountKeyLength = key.length;
+        }
+      }
+      if (!mount?.directory) return false;
+      // Rebuild every level between the mount and the path, each as a child
+      // of the one above, so breadcrumbs and the tree have the whole chain.
+      const sep = path.includes("\\") ? "\\" : "/";
+      const mountDir = mount.directory.replace(/[\\/]+$/, "");
+      const rest = path
+        .slice(mountDir.length)
+        .split(/[\\/]+/)
+        .filter(Boolean);
+      const additions: Array<[FolderId, FolderRecord]> = [];
+      let parentId: FolderId = mount.id;
+      let current = mountDir;
+      for (const segment of rest) {
+        current = `${current}${sep}${segment}`;
+        const record = diskSubfolderRecord(current, segment, parentId);
+        additions.push([parentId, record]);
+        parentId = record.id;
+      }
+      setDiskSubfolders((prev) => {
+        const next = new Map(prev);
+        for (const [parent, record] of additions) {
+          const siblings = next.get(parent) ?? [];
+          if (!siblings.some((f) => f.id === record.id)) {
+            next.set(parent, [...siblings, record]);
+          }
+        }
+        return next;
+      });
+      return true;
+    },
+    [storedFolders],
+  );
+
   const value = useMemo<FolderContextValue>(
     () => ({
       folders,
@@ -698,6 +1001,9 @@ export function FolderProvider({ children }: FolderProviderProps) {
       refresh,
       pullFromServer,
       createFolder,
+      mountLocalFolder,
+      registerDiskSubfolders,
+      resolveDiskFolder,
       renameFolder,
       moveFolder,
       updateFolderAppearance,
@@ -717,6 +1023,9 @@ export function FolderProvider({ children }: FolderProviderProps) {
       refresh,
       pullFromServer,
       createFolder,
+      mountLocalFolder,
+      registerDiskSubfolders,
+      resolveDiskFolder,
       renameFolder,
       moveFolder,
       updateFolderAppearance,

frontend/editor/src/core/contexts/file/fileActions.ts

@@ -273,6 +273,12 @@ interface AddFileOptions {
   /** When true, marks every added stub as derivedFromTool so the policy
    *  auto-run skips it — used for policy outputs imported via addFiles. */
   derivedFromTool?: boolean;
+  /**
+   * The folder every added file is born into — membership set at creation, atomically
+   * with the stub, instead of a separate move that can fail after the file already
+   * landed somewhere else.
+   */
+  folderId?: string;
 }
 
 /**
@@ -444,6 +450,9 @@ export async function addFiles(
       // Create new filestub with minimal metadata; hydrate thumbnails/processedFile asynchronously
       const fileStub = createNewStirlingFileStub(file, fileId);
       if (options.derivedFromTool) fileStub.derivedFromTool = true;
+      if (options.folderId) {
+        fileStub.folderId = options.folderId as StirlingFileStub["folderId"];
+      }
 
       // Early encryption detection for PDFs — set the flag before dispatch so the
       // viewer gate and modal queue pick it up immediately instead of after hydration

frontend/editor/src/core/hooks/useFileHandler.ts

@@ -17,6 +17,8 @@ export const useFileHandler = () => {
         autoUnzip?: boolean;
         /** Skip the upload metric - the file isn't new to the system (e.g. a copy). */
         skipUploadTracking?: boolean;
+        /** Folder every added file is born into (see AddFileOptions). */
+        folderId?: string;
       } = {},
     ): Promise<StirlingFile[]> => {
       // Merge default options with passed options - passed options take precedence

frontend/editor/src/core/hooks/useLazyThumbnail.ts

@@ -3,6 +3,7 @@ import type { FileId } from "@app/types/file";
 import { useFileManagement } from "@app/contexts/FileContext";
 import { useIndexedDB } from "@app/contexts/IndexedDBContext";
 import { generateThumbnailForFile } from "@app/utils/thumbnailUtils";
+import { readDiskFile } from "@app/services/localFolderContents";
 
 const THUMBNAIL_SIZE_LIMIT = 100 * 1024 * 1024; // 100MB
 
@@ -15,7 +16,7 @@ const LAZY_THUMB_CONCURRENCY = 2;
 let activeLazyThumbs = 0;
 const lazyThumbQueue: Array<() => Promise<void>> = [];
 
-function scheduleLazyThumb(task: () => Promise<void>): void {
+export function scheduleLazyThumb(task: () => Promise<void>): void {
   lazyThumbQueue.push(task);
   drainLazyThumbQueue();
 }
@@ -80,3 +81,92 @@ export function useLazyThumbnail(
 
   return thumb;
 }
+
+// Keyed by path + mtime + size: an unchanged file never renders twice, an edited one does.
+const diskThumbCache = new Map<string, string>();
+// Bounded by bytes, not entries: image thumbnails are data URLs that track the
+// source, so 300 photos would pin gigabytes of strings for the process lifetime.
+const DISK_THUMB_CACHE_MAX_BYTES = 48 * 1024 * 1024;
+let diskThumbCacheBytes = 0;
+
+function cacheDiskThumb(key: string, url: string): void {
+  const prior = diskThumbCache.get(key);
+  if (prior !== undefined) diskThumbCacheBytes -= prior.length;
+  while (
+    diskThumbCacheBytes + url.length > DISK_THUMB_CACHE_MAX_BYTES &&
+    diskThumbCache.size > 0
+  ) {
+    // Insertion order makes this FIFO; an evicted thumbnail re-renders on revisit.
+    const oldest = diskThumbCache.keys().next().value!;
+    diskThumbCacheBytes -= diskThumbCache.get(oldest)!.length;
+    diskThumbCache.delete(oldest);
+  }
+  diskThumbCache.set(key, url);
+  diskThumbCacheBytes += url.length;
+}
+
+// Reading the bytes is the expensive step, so only for types the generator renders.
+const THUMBABLE_EXTENSIONS = new Set([
+  "pdf",
+  "png",
+  "jpg",
+  "jpeg",
+  "gif",
+  "webp",
+  "bmp",
+  "svg",
+]);
+
+function canEverThumbnail(name: string): boolean {
+  const ext = name.includes(".") ? name.split(".").pop()!.toLowerCase() : "";
+  return THUMBABLE_EXTENSIONS.has(ext);
+}
+
+/**
+ * Thumbnail for a disk-listed file, through the same generator and the same concurrency
+ * gate as stored files — a mounted folder's rows fill in progressively alongside
+ * everything else instead of stampeding the disk.
+ */
+export function useDiskThumbnail(entry: {
+  path: string;
+  name: string;
+  sizeBytes: number;
+  lastModified: number;
+}): string | undefined {
+  const key = `${entry.path}|${entry.lastModified}|${entry.sizeBytes}`;
+  const [thumb, setThumb] = useState<string | undefined>(() => {
+    const hit = diskThumbCache.get(key);
+    return hit === "" ? undefined : hit;
+  });
+
+  useEffect(() => {
+    const cached = diskThumbCache.get(key);
+    if (cached !== undefined) {
+      setThumb(cached === "" ? undefined : cached);
+      return;
+    }
+    if (entry.sizeBytes >= THUMBNAIL_SIZE_LIMIT) return;
+    if (!canEverThumbnail(entry.name)) return;
+    let cancelled = false;
+    scheduleLazyThumb(async () => {
+      if (cancelled || diskThumbCache.has(key)) return;
+      try {
+        const file = await readDiskFile(entry);
+        if (!file || cancelled) return;
+        const url = await generateThumbnailForFile(file);
+        // "" is cached too: a failed/oversized render should not retry on
+        // every re-mount of the same row.
+        cacheDiskThumb(key, url);
+        if (!cancelled && url) setThumb(url);
+      } catch {
+        cacheDiskThumb(key, "");
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+    // The key encodes every field of `entry` this effect reads.
+  }, [key]);
+
+  return thumb;
+}

frontend/editor/src/core/hooks/useNewFolderFlow.ts

@@ -0,0 +1,70 @@
+import { useCallback } from "react";
+import { useTranslation } from "react-i18next";
+import { useNavigate } from "react-router-dom";
+import { useFolders } from "@app/contexts/FolderContext";
+import { useFilesPage } from "@app/contexts/FilesPageContext";
+import { canPickDirectory, pickDirectory } from "@app/services/directoryPicker";
+import { useServerFolderBlock } from "@app/hooks/useServerFolderBlock";
+
+/** The folder-creation flows, shared by every surface that offers them so they
+ *  cannot drift apart. */
+export function useNewFolderFlow() {
+  const { t } = useTranslation();
+  const folders = useFolders();
+  const { openNewFolderDialog } = useFilesPage();
+  const navigate = useNavigate();
+  const serverFolderBlock = useServerFolderBlock();
+
+  // No dialog: the picker is the whole interaction and the directory names the folder.
+  const addLocalFolder = useCallback(async () => {
+    try {
+      const picked = await pickDirectory();
+      if (!picked) return;
+      const record = await folders.mountLocalFolder(picked.path, picked.name);
+      // The path owns folder selection: setting state here races the effect that
+      // re-runs with the old pathname and snaps back to root.
+      navigate(`/files/${record.id}`);
+    } catch (err) {
+      folders.setError(
+        err instanceof Error
+          ? t("filesPage.error.addFolderFailedDetail", {
+              message: err.message,
+              defaultValue: `Could not add the folder: ${err.message}`,
+            })
+          : t("filesPage.error.addFolderFailed", "Could not add the folder."),
+      );
+    }
+  }, [folders, navigate, t]);
+
+  // Single-click New folder for surfaces with no menu: the picker where the build
+  // can see the disk, a server folder on the web, and blocked rather than silent
+  // when the server cannot take one. Inside a folder the kind is inherited.
+  const createFolderHere = useCallback(() => {
+    if (folders.currentFolderId !== null) {
+      openNewFolderDialog(folders.currentFolderId);
+      return;
+    }
+    if (canPickDirectory) {
+      void addLocalFolder();
+      return;
+    }
+    // Backstop: surfaces disable themselves, so a click here means stale UI.
+    if (serverFolderBlock === null) {
+      openNewFolderDialog(null, "server");
+    }
+  }, [
+    addLocalFolder,
+    folders.currentFolderId,
+    openNewFolderDialog,
+    serverFolderBlock,
+  ]);
+
+  // Why the single-click surfaces are disabled, or null. Only the web root blocks:
+  // desktop always has the picker, and subfolders inherit their kind.
+  const createFolderHereBlockedReason =
+    folders.currentFolderId === null && !canPickDirectory
+      ? serverFolderBlock
+      : null;
+
+  return { addLocalFolder, createFolderHere, createFolderHereBlockedReason };
+}

frontend/editor/src/core/hooks/useServerFolderBlock.ts

@@ -0,0 +1,27 @@
+import { useTranslation } from "react-i18next";
+import { useAuth } from "@app/auth/UseSession";
+import { useAppConfig } from "@app/contexts/AppConfigContext";
+import { useFolders } from "@app/contexts/FolderContext";
+
+/** Why a server folder can't be created right now, or null when it can. */
+export function useServerFolderBlock(): string | null {
+  const { t } = useTranslation();
+  const { isAnonymous } = useAuth();
+  const { config: appConfig } = useAppConfig();
+  const folders = useFolders();
+  if (isAnonymous) {
+    return t("filesPage.signInRequired", "Sign in to use cloud storage.");
+  }
+  // Two different problems, two different next steps: storage off is an
+  // admin setting; unreachable is a connectivity state that fixes itself.
+  if (appConfig?.storageEnabled !== true) {
+    return t(
+      "filesPage.newFolderStorageDisabled",
+      "Server folder storage isn't enabled.",
+    );
+  }
+  if (!folders.serverReachable) {
+    return t("filesPage.syncError.network", "Could not reach the server.");
+  }
+  return null;
+}

frontend/editor/src/core/pages/HomePage.tsx

@@ -56,6 +56,9 @@ import {
   useFilesPage,
 } from "@app/contexts/FilesPageContext";
 import { useFolders } from "@app/contexts/FolderContext";
+import { folderKind } from "@app/types/folder";
+import { useServerFolderBlock } from "@app/hooks/useServerFolderBlock";
+import { useNewFolderFlow } from "@app/hooks/useNewFolderFlow";
 import { useFileHandler } from "@app/hooks/useFileHandler";
 import { FolderTreePanel } from "@app/components/filesPage/FolderTreePanel";
 import type { FileSidebarProps } from "@app/components/shared/FileSidebar";
@@ -771,6 +774,8 @@ const MyFilesSidebarOverrides = forwardRef<HTMLDivElement, FileSidebarProps>(
     const filesPage = useFilesPage();
     const folders = useFolders();
     const { addFiles } = useFileHandler();
+    const { createFolderHere, createFolderHereBlockedReason } =
+      useNewFolderFlow();
 
     const handleUpload = useCallback(
       async (files: File[]) => {
@@ -787,12 +792,19 @@ const MyFilesSidebarOverrides = forwardRef<HTMLDivElement, FileSidebarProps>(
       [addFiles, filesPage, folders.currentFolderId],
     );
 
-    const newFolderDisabledReason = !folders.serverReachable
-      ? t(
-          "filesPage.newFolderStorageDisabled",
-          "Server folder storage isn't enabled. Ask your admin to turn it on.",
-        )
+    // Kind-aware: only a server folder's subfolder needs the server, and a mounted
+    // directory takes no subfolders from here at all.
+    const railCurrentFolder = folders.currentFolderId
+      ? folders.foldersById.get(folders.currentFolderId)
+      : undefined;
+    const railCurrentKind = railCurrentFolder
+      ? folderKind(railCurrentFolder)
       : null;
+    const serverFolderBlock = useServerFolderBlock();
+    const newFolderDisabledReason =
+      railCurrentKind === "server"
+        ? serverFolderBlock
+        : createFolderHereBlockedReason;
 
     return (
       <FileSidebar
@@ -803,7 +815,7 @@ const MyFilesSidebarOverrides = forwardRef<HTMLDivElement, FileSidebarProps>(
         extraAction={{
           icon: <CreateNewFolderIcon />,
           label: t("filesPage.newFolder", "New folder"),
-          onClick: () => filesPage.openNewFolderDialog(),
+          onClick: createFolderHere,
           disabled: newFolderDisabledReason !== null,
           disabledTooltip: newFolderDisabledReason ?? undefined,
           testId: "files-rail-new-folder",

frontend/editor/src/core/services/directoryPicker.ts

@@ -0,0 +1,15 @@
+/** Picking a directory on the machine, as a real filesystem path. */
+
+export interface PickedDirectory {
+  /** Absolute path, as the platform writes it. */
+  path: string;
+  /** The directory's own name — the mounted folder's display name. */
+  name: string;
+}
+
+export const canPickDirectory = false;
+
+/** Ask the user for a directory; null when cancelled (or unsupported). */
+export async function pickDirectory(): Promise<PickedDirectory | null> {
+  return null;
+}

frontend/editor/src/core/services/fileSyncService.ts

@@ -11,6 +11,7 @@ import { alert } from "@app/components/toast";
 import { StirlingFileStub, StirlingFile } from "@app/types/fileContext";
 import { FileId } from "@app/types/fileContext";
 import { FolderId, parseFolderId } from "@app/types/folder";
+import { virtualFolderStorage } from "@app/services/virtualFolderStorage";
 import {
   isZipBundle,
   loadShareBundleEntries,
@@ -119,6 +120,15 @@ export async function reconcileServerFiles(
   }
 
   let combinedStubs: StirlingFileStub[];
+  // Virtual folders are browser-owned, so a stub sitting in one must keep its
+  // membership through the reconcile — the server's folderId (always null for them) is
+  // not an opinion about it.
+  const virtualFolderIds = new Set<FolderId>(
+    await virtualFolderStorage
+      .getAllFolders()
+      .then((folders) => folders.map((folder) => folder.id))
+      .catch(() => []),
+  );
   const localRemoteIds = new Set(
     localStubs
       .map((s) => s.remoteStorageId)
@@ -202,7 +212,12 @@ export async function reconcileServerFiles(
         // Server is authoritative for cloud-stored files. Don't fall back to
         // stub.folderId on null - that would resurrect a stale folder pointer
         // after the server SET_NULL'd it (e.g. owner deleted the folder).
-        folderId: safeParseFolderId(serverFile.folderId),
+        // EXCEPT when the stub sits in a browser-owned (virtual) folder: the
+        // server has never heard of that folder, so its null says nothing
+        // about the membership and must not eject the file from it.
+        folderId: virtualFolderIds.has((stub.folderId ?? "") as FolderId)
+          ? stub.folderId
+          : safeParseFolderId(serverFile.folderId),
       };
     });
 

frontend/editor/src/core/services/folderStorage.ts

@@ -11,12 +11,24 @@
  * are all the server's job now.
  */
 
-import { FolderId, FolderRecord } from "@app/types/folder";
+import { FolderId, FolderRecord, folderKind } from "@app/types/folder";
 import {
   indexedDBManager,
   DATABASE_CONFIGS,
 } from "@app/services/indexedDBManager";
 
+/**
+ * This cache is wiped and rewritten from the server's response on every sync, so a
+ * non-server folder stored here would silently vanish on the next pull.
+ */
+function requireServerFolder(folder: FolderRecord): void {
+  if (folderKind(folder) !== "server") {
+    throw new Error(
+      `folderStorage caches server folders only; got kind "${folderKind(folder)}" for ${folder.id}`,
+    );
+  }
+}
+
 class FolderStorageService {
   private readonly dbConfig = DATABASE_CONFIGS.FILES;
   private readonly storeName = "folders";
@@ -43,6 +55,7 @@ class FolderStorageService {
         reject(transaction.error ?? new Error("folder cache replace aborted"));
       store.clear();
       for (const folder of folders) {
+        requireServerFolder(folder);
         store.put(folder);
       }
     });
@@ -50,6 +63,7 @@ class FolderStorageService {
 
   /** Insert or overwrite a single folder in the cache. */
   async upsertFolder(folder: FolderRecord): Promise<void> {
+    requireServerFolder(folder);
     const db = await this.getDatabase();
     await new Promise<void>((resolve, reject) => {
       const transaction = db.transaction([this.storeName], "readwrite");

frontend/editor/src/core/services/folderSyncService.ts

@@ -51,6 +51,9 @@ function toFolderRecord(dto: ServerFolder): FolderRecord {
     dto.parentFolderId === null ? null : parseFolderId(dto.parentFolderId);
   return {
     id,
+    // Everything that comes off this wire is a server folder by definition;
+    // virtual and local folders never round-trip through the server at all.
+    kind: "server",
     name: dto.name,
     parentFolderId,
     color: dto.color ?? undefined,

frontend/editor/src/core/services/indexedDBManager.migration.test.ts

@@ -399,4 +399,71 @@ describe("IndexedDB migration (FILES store)", () => {
       TARGET_VERSION,
     );
   });
+
+  test("a v10 profile missing local_folders upgrades to v11 with the full schema", async () => {
+    // v10 briefly existed with only one of the two browser-folder stores.
+    await new Promise<void>((resolve, reject) => {
+      const req = indexedDB.open(DB_NAME, 10);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        db.createObjectStore("files", { keyPath: "id" });
+        db.createObjectStore("folders", { keyPath: "id" });
+        db.createObjectStore("virtual_folders", { keyPath: "id" });
+        // local_folders deliberately absent.
+      };
+      req.onsuccess = () => {
+        req.result.close();
+        resolve();
+      };
+      req.onerror = () => reject(req.error);
+    });
+
+    const db = await indexedDBManager.openDatabase(DATABASE_CONFIGS.FILES);
+    const names = Array.from(db.objectStoreNames);
+    expect(names).toContain("local_folders");
+    expect(names).toContain("virtual_folders");
+    expect(db.version).toBe(TARGET_VERSION);
+    indexedDBManager.closeDatabase(DB_NAME);
+  });
+
+  test("v9 -> latest adds virtual_folders without touching files or folders", async () => {
+    // Seed a database shaped like the v9 schema: files + folders, no
+    // virtual_folders yet, with a row in each that must survive the upgrade.
+    await new Promise<void>((resolve, reject) => {
+      const req = indexedDB.open(DB_NAME, 9);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        db.createObjectStore("files", { keyPath: "id" });
+        db.createObjectStore("folders", { keyPath: "id" });
+      };
+      req.onsuccess = () => {
+        const db = req.result;
+        const tx = db.transaction(["files", "folders"], "readwrite");
+        tx.objectStore("files").put({ id: "file-1", folderId: null });
+        tx.objectStore("folders").put({ id: "folder-1", name: "Kept" });
+        tx.oncomplete = () => {
+          db.close();
+          resolve();
+        };
+        tx.onerror = () => reject(tx.error);
+      };
+      req.onerror = () => reject(req.error);
+    });
+
+    await indexedDBManager.openDatabase(DATABASE_CONFIGS.FILES);
+    indexedDBManager.closeDatabase(DB_NAME);
+
+    const stores = await getObjectStoreNames();
+    expect(stores).toContain("virtual_folders");
+    expect(stores).toContain("local_folders");
+    expect(stores).toContain("files");
+    expect(stores).toContain("folders");
+
+    const rows = (await readAllFiles()) as Array<Record<string, unknown>>;
+    expect(rows.map((row) => row.id)).toEqual(["file-1"]);
+
+    expect(await indexedDBManager.getDatabaseVersion(DB_NAME)).toBe(
+      TARGET_VERSION,
+    );
+  });
 });

frontend/editor/src/core/services/indexedDBManager.ts

@@ -465,7 +465,9 @@ class IndexedDBManager {
 export const DATABASE_CONFIGS = {
   FILES: {
     name: "stirling-pdf-files",
-    version: 9,
+    // v10 existed briefly with only one of the two browser-folder stores; v11 declares
+    // both, so every v10 profile upgrades to a full schema.
+    version: 11,
     stores: [
       {
         name: "files",
@@ -492,6 +494,27 @@ export const DATABASE_CONFIGS = {
           { name: "createdAt", keyPath: "createdAt", unique: false },
         ],
       },
+      {
+        name: "local_folders",
+        keyPath: "id",
+        indexes: [{ name: "name", keyPath: "name", unique: false }],
+      },
+      // Browser-owned folders (kind "virtual"), deliberately a separate store from
+      // `folders`: that one is a cache the server sync wipes wholesale on every pull,
+      // and these rows have no server copy to be restored from.
+      {
+        name: "virtual_folders",
+        keyPath: "id",
+        indexes: [
+          {
+            name: "parentFolderId",
+            keyPath: "parentFolderId",
+            unique: false,
+          },
+          { name: "name", keyPath: "name", unique: false },
+          { name: "createdAt", keyPath: "createdAt", unique: false },
+        ],
+      },
     ],
   } as DatabaseConfig,
 

frontend/editor/src/core/services/localFolderContents.ts

@@ -0,0 +1,54 @@
+/** One file inside a mounted directory, as the file manager lists it. */
+export interface DiskFileEntry {
+  /** Absolute path — the file's identity here; nothing about it is stored. */
+  path: string;
+  name: string;
+  sizeBytes: number;
+  lastModified: number;
+}
+
+export interface DiskDirEntry {
+  path: string;
+  name: string;
+}
+
+/** What one look at a mounted directory yields. */
+export interface DiskListing {
+  files: DiskFileEntry[];
+  directories: DiskDirEntry[];
+}
+
+export const canListDirectory = false;
+
+/**
+ * The regular files and subdirectories directly inside `directory` — one level, never
+ * recursive; a subdirectory is listed only when entered.
+ */
+export async function listDirectory(
+  _directory: string,
+): Promise<DiskListing | null> {
+  return null;
+}
+
+export async function makeDiskDirectory(
+  _parent: string,
+  _name: string,
+): Promise<string | null> {
+  return null;
+}
+
+/** Read one listed file's bytes as a File, ready for the workbench. */
+export async function readDiskFile(
+  _entry: DiskFileEntry,
+): Promise<File | null> {
+  return null;
+}
+
+/** Write a file into a mounted directory, under a name that never clobbers an existing one. */
+export async function writeDiskFile(
+  _directory: string,
+  _name: string,
+  _bytes: Blob,
+): Promise<string | null> {
+  return null;
+}

frontend/editor/src/core/services/localFolderStorage.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test, beforeEach } from "vitest";
+import "fake-indexeddb/auto";
+import { IDBFactory } from "fake-indexeddb";
+import {
+  localFolderStorage,
+  directoryKey,
+} from "@app/services/localFolderStorage";
+import {
+  indexedDBManager,
+  DATABASE_CONFIGS,
+} from "@app/services/indexedDBManager";
+
+/**
+ * A mount is a pointer at a directory, and one directory must never have two pointers —
+ * the rows would be two names for one truth.
+ */
+describe("localFolderStorage", () => {
+  beforeEach(() => {
+    indexedDBManager.closeDatabase(DATABASE_CONFIGS.FILES.name);
+    globalThis.indexedDB = new IDBFactory();
+  });
+
+  test("directoryKey equates the spellings a case-insensitive filesystem does", () => {
+    const key = directoryKey("C:\\Users\\Reece\\Downloads");
+    expect(directoryKey("c:\\users\\reece\\downloads")).toBe(key);
+    expect(directoryKey("C:\\Users\\Reece\\Downloads\\")).toBe(key);
+    expect(directoryKey("C:/Users/Reece/Downloads")).toBe(key);
+    expect(directoryKey("C:\\Users\\\\Reece\\Downloads")).toBe(key);
+
+    expect(directoryKey("\\\\server\\share\\docs")).toBe(
+      directoryKey("//SERVER/share/docs/"),
+    );
+
+    // POSIX paths are genuinely case-sensitive; only the separator rules apply.
+    expect(directoryKey("/home/Reece/")).toBe(directoryKey("/home/Reece"));
+    expect(directoryKey("/home/Reece")).not.toBe(directoryKey("/home/reece"));
+  });
+
+  test("mounting the same directory under another spelling hands back the existing record", async () => {
+    const first = await localFolderStorage.mountDirectory(
+      "C:\\Users\\Reece\\Downloads",
+      "Downloads",
+    );
+    const again = await localFolderStorage.mountDirectory(
+      "c:/users/reece/downloads/",
+      "downloads",
+    );
+    expect(again.id).toBe(first.id);
+    expect(await localFolderStorage.getAllFolders()).toHaveLength(1);
+  });
+
+  test("a subdirectory of a mount gets its own mount; that is the only way to reach it", async () => {
+    const parent = await localFolderStorage.mountDirectory(
+      "C:\\Users\\Reece\\Downloads",
+      "Downloads",
+    );
+    const child = await localFolderStorage.mountDirectory(
+      "C:\\Users\\Reece\\Downloads\\Invoices",
+      "Invoices",
+    );
+    expect(child.id).not.toBe(parent.id);
+    expect(await localFolderStorage.getAllFolders()).toHaveLength(2);
+  });
+});

frontend/editor/src/core/services/localFolderStorage.ts

@@ -0,0 +1,119 @@
+/**
+ * The record of directories mounted into the file manager (kind "local"): a pointer at
+ * a directory, nothing more.
+ */
+
+import {
+  FolderId,
+  FolderRecord,
+  folderKind,
+  createFolderId,
+  pickFolderColor,
+} from "@app/types/folder";
+import {
+  indexedDBManager,
+  DATABASE_CONFIGS,
+} from "@app/services/indexedDBManager";
+
+/** One directory, one key — regardless of how the picker spelled the path. */
+export function directoryKey(directory: string): string {
+  let key = directory.replace(/\\/g, "/");
+  const unc = key.startsWith("//");
+  key = key.replace(/\/{2,}/g, "/");
+  if (unc) key = `/${key}`;
+  if (key.length > 1 && !/^[a-zA-Z]:\/$/.test(key)) {
+    key = key.replace(/\/+$/, "");
+  }
+  if (/^[a-zA-Z]:/.test(key) || unc) {
+    key = key.toLowerCase();
+  }
+  return key;
+}
+
+function requireLocalFolder(folder: FolderRecord): void {
+  if (folderKind(folder) !== "local") {
+    throw new Error(
+      `localFolderStorage owns local folders only; got kind "${folderKind(folder)}" for ${folder.id}`,
+    );
+  }
+}
+
+class LocalFolderStorageService {
+  private readonly dbConfig = DATABASE_CONFIGS.FILES;
+  private readonly storeName = "local_folders";
+
+  private async getDatabase(): Promise<IDBDatabase> {
+    return indexedDBManager.openDatabase(this.dbConfig);
+  }
+
+  async getAllFolders(): Promise<FolderRecord[]> {
+    const db = await this.getDatabase();
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], "readonly");
+      const store = transaction.objectStore(this.storeName);
+      const request = store.getAll();
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () =>
+        resolve((request.result as FolderRecord[]) ?? []);
+    });
+  }
+
+  /**
+   * Mount a directory, or hand back the existing record for one already mounted: two
+   * rows for one directory would be two names for one truth.
+   */
+  async mountDirectory(directory: string, name: string): Promise<FolderRecord> {
+    const key = directoryKey(directory);
+    const folders = await this.getAllFolders();
+    const existing = folders.find(
+      (folder) => directoryKey(folder.directory ?? "") === key,
+    );
+    if (existing) return existing;
+    const now = Date.now();
+    const record: FolderRecord = {
+      id: createFolderId(),
+      kind: "local",
+      name,
+      parentFolderId: null,
+      directory,
+      color: pickFolderColor(name),
+      createdAt: now,
+      updatedAt: now,
+    };
+    requireLocalFolder(record);
+    const db = await this.getDatabase();
+    await new Promise<void>((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], "readwrite");
+      const store = transaction.objectStore(this.storeName);
+      const req = store.put(record);
+      req.onerror = () => reject(req.error);
+      req.onsuccess = () => resolve();
+    });
+    return record;
+  }
+
+  /** Remove the mount. The directory on disk is untouched, always. */
+  async removeFolder(id: FolderId): Promise<void> {
+    const db = await this.getDatabase();
+    await new Promise<void>((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], "readwrite");
+      const store = transaction.objectStore(this.storeName);
+      const req = store.delete(id);
+      req.onerror = () => reject(req.error);
+      req.onsuccess = () => resolve();
+    });
+  }
+
+  async clearAll(): Promise<void> {
+    const db = await this.getDatabase();
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], "readwrite");
+      const store = transaction.objectStore(this.storeName);
+      const request = store.clear();
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve();
+    });
+  }
+}
+
+export const localFolderStorage = new LocalFolderStorageService();

frontend/editor/src/core/services/mountWrites.ts

@@ -0,0 +1,38 @@
+import { writeDiskFile } from "@app/services/localFolderContents";
+
+export interface MountWriteItem {
+  name: string;
+  /** Pulled lazily, one file at a time — a batch never sits in memory whole. */
+  bytes: () => Promise<Blob | null>;
+}
+
+/**
+ * Write named blobs into a mounted directory - the one engine behind both uploading
+ * into a mount and moving library files into one, so failure accounting and collision
+ * behaviour cannot drift apart.
+ */
+export async function writeIntoMount(
+  directory: string | undefined,
+  items: MountWriteItem[],
+): Promise<{ written: boolean[]; failedCount: number }> {
+  const written: boolean[] = items.map(() => false);
+  let failedCount = 0;
+  for (let i = 0; i < items.length; i++) {
+    try {
+      const blob = directory ? await items[i].bytes() : null;
+      const result =
+        blob && directory
+          ? await writeDiskFile(directory, items[i].name, blob)
+          : null;
+      if (result === null) {
+        failedCount += 1;
+      } else {
+        written[i] = true;
+      }
+    } catch (err) {
+      console.warn("[mountWrites] write into mount failed", err);
+      failedCount += 1;
+    }
+  }
+  return { written, failedCount };
+}

frontend/editor/src/core/services/virtualFolderStorage.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, test, beforeEach } from "vitest";
+import "fake-indexeddb/auto";
+import { IDBFactory } from "fake-indexeddb";
+import { virtualFolderStorage } from "@app/services/virtualFolderStorage";
+import { folderStorage } from "@app/services/folderStorage";
+import {
+  indexedDBManager,
+  DATABASE_CONFIGS,
+} from "@app/services/indexedDBManager";
+
+/**
+ * Virtual folders have no server to be authoritative, so the invariants the
+ * server enforces for its folders (no cycles, bounded depth, subtree deletes
+ * that report every removed id) are this module's own responsibility.
+ */
+describe("virtualFolderStorage", () => {
+  beforeEach(() => {
+    indexedDBManager.closeDatabase(DATABASE_CONFIGS.FILES.name);
+    globalThis.indexedDB = new IDBFactory();
+  });
+
+  test("creates rows stamped virtual, invisible to the server folder cache", async () => {
+    const created = await virtualFolderStorage.createFolder("Research", null);
+    expect(created.kind).toBe("virtual");
+
+    // Same DB, different store: the server cache must not see it, because a
+    // sync wipes that cache wholesale and would silently destroy the row.
+    expect(await folderStorage.getAllFolders()).toEqual([]);
+    expect(await virtualFolderStorage.getAllFolders()).toEqual([created]);
+  });
+
+  test("the server cache refuses a virtual row outright", async () => {
+    const virtual = await virtualFolderStorage.createFolder("Research", null);
+    await expect(folderStorage.upsertFolder(virtual)).rejects.toThrow(
+      /server folders only/,
+    );
+  });
+
+  test("refuses to move a folder into its own subtree", async () => {
+    const parent = await virtualFolderStorage.createFolder("a", null);
+    const child = await virtualFolderStorage.createFolder("b", parent.id);
+    const grandchild = await virtualFolderStorage.createFolder("c", child.id);
+
+    await expect(
+      virtualFolderStorage.moveFolder(parent.id, grandchild.id),
+    ).rejects.toThrow(/own subtree/);
+    await expect(
+      virtualFolderStorage.moveFolder(parent.id, parent.id),
+    ).rejects.toThrow(/into itself/);
+  });
+
+  test("deleting a folder removes its whole subtree and reports every id", async () => {
+    const parent = await virtualFolderStorage.createFolder("a", null);
+    const child = await virtualFolderStorage.createFolder("b", parent.id);
+    const grandchild = await virtualFolderStorage.createFolder("c", child.id);
+    const bystander = await virtualFolderStorage.createFolder("keep", null);
+
+    const removed = await virtualFolderStorage.deleteFolder(parent.id);
+
+    // Every removed id is reported so the caller can unlink files that
+    // referenced them — the same contract as the server delete.
+    expect([...removed].sort()).toEqual(
+      [parent.id, child.id, grandchild.id].sort(),
+    );
+    expect(await virtualFolderStorage.getAllFolders()).toEqual([bystander]);
+  });
+
+  test("refuses to nest past the depth cap", async () => {
+    let parentId = (await virtualFolderStorage.createFolder("d0", null)).id;
+    for (let i = 1; i < 64; i += 1) {
+      parentId = (await virtualFolderStorage.createFolder(`d${i}`, parentId))
+        .id;
+    }
+    await expect(
+      virtualFolderStorage.createFolder("too-deep", parentId),
+    ).rejects.toThrow(/depth limit/);
+  });
+});

frontend/editor/src/core/services/virtualFolderStorage.ts

@@ -0,0 +1,219 @@
+/**
+ * The system of record for kind "virtual" folders - rows this store owns rather than
+ * caches.
+ */
+
+import {
+  FolderId,
+  FolderRecord,
+  folderKind,
+  createFolderId,
+  pickFolderColor,
+} from "@app/types/folder";
+import {
+  indexedDBManager,
+  DATABASE_CONFIGS,
+} from "@app/services/indexedDBManager";
+
+/** Mirrors FolderService.MAX_FOLDER_DEPTH so virtual trees can't out-nest server ones. */
+const MAX_FOLDER_DEPTH = 64;
+
+function requireVirtualFolder(folder: FolderRecord): void {
+  if (folderKind(folder) !== "virtual") {
+    throw new Error(
+      `virtualFolderStorage owns virtual folders only; got kind "${folderKind(folder)}" for ${folder.id}`,
+    );
+  }
+}
+
+class VirtualFolderStorageService {
+  private readonly dbConfig = DATABASE_CONFIGS.FILES;
+  private readonly storeName = "virtual_folders";
+
+  private async getDatabase(): Promise<IDBDatabase> {
+    return indexedDBManager.openDatabase(this.dbConfig);
+  }
+
+  async getAllFolders(): Promise<FolderRecord[]> {
+    const db = await this.getDatabase();
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], "readonly");
+      const store = transaction.objectStore(this.storeName);
+      const request = store.getAll();
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () =>
+        resolve((request.result as FolderRecord[]) ?? []);
+    });
+  }
+
+  async getFolder(id: FolderId): Promise<FolderRecord | null> {
+    const db = await this.getDatabase();
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], "readonly");
+      const store = transaction.objectStore(this.storeName);
+      const request = store.get(id);
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () =>
+        resolve((request.result as FolderRecord | undefined) ?? null);
+    });
+  }
+
+  /**
+   * Create a virtual folder under `parent` (null = root), which must itself be
+   * virtual: hung off a server folder, a server-side delete orphans the subtree.
+   */
+  async createFolder(
+    name: string,
+    parentFolderId: FolderId | null,
+  ): Promise<FolderRecord> {
+    if (parentFolderId !== null) {
+      await this.requireWithinDepth(parentFolderId);
+    }
+    const now = Date.now();
+    const record: FolderRecord = {
+      id: createFolderId(),
+      kind: "virtual",
+      name,
+      parentFolderId,
+      color: pickFolderColor(name),
+      createdAt: now,
+      updatedAt: now,
+    };
+    await this.put(record);
+    return record;
+  }
+
+  /** Rename / recolour / re-icon in place. Structure is moveFolder's job. */
+  async updateFolder(
+    id: FolderId,
+    updates: Partial<Pick<FolderRecord, "name" | "color" | "icon">>,
+  ): Promise<FolderRecord | null> {
+    const existing = await this.getFolder(id);
+    if (!existing) return null;
+    const next: FolderRecord = {
+      ...existing,
+      ...updates,
+      updatedAt: Date.now(),
+    };
+    await this.put(next);
+    return next;
+  }
+
+  /**
+   * Reparent a folder (null = to root), refusing moves that would make the
+   * tree lie: under itself or its own descendant (a cycle — the subtree would
+   * fall out of every walk), or deeper than the depth cap.
+   */
+  async moveFolder(
+    id: FolderId,
+    newParentId: FolderId | null,
+  ): Promise<FolderRecord | null> {
+    const existing = await this.getFolder(id);
+    if (!existing) return null;
+    if (newParentId !== null) {
+      if (newParentId === id) {
+        throw new Error("Cannot move a folder into itself");
+      }
+      const ancestors = await this.requireWithinDepth(newParentId);
+      if (ancestors.has(id)) {
+        throw new Error("Cannot move a folder into its own subtree");
+      }
+    }
+    const next: FolderRecord = {
+      ...existing,
+      parentFolderId: newParentId,
+      updatedAt: Date.now(),
+    };
+    await this.put(next);
+    return next;
+  }
+
+  /**
+   * Delete a folder and its whole virtual subtree, returning every removed id
+   * so the caller can unlink files that referenced them — mirroring the shape
+   * of the server delete, which reports removedFolderIds for the same reason.
+   */
+  async deleteFolder(id: FolderId): Promise<FolderId[]> {
+    const all = await this.getAllFolders();
+    const childrenByParent = new Map<FolderId | null, FolderRecord[]>();
+    for (const folder of all) {
+      const siblings = childrenByParent.get(folder.parentFolderId) ?? [];
+      siblings.push(folder);
+      childrenByParent.set(folder.parentFolderId, siblings);
+    }
+    // `removed` doubles as the BFS queue (index-walked; shift() would
+    // reindex the array on every visit).
+    const removed: FolderId[] = [id];
+    for (let head = 0; head < removed.length; head++) {
+      for (const child of childrenByParent.get(removed[head]) ?? []) {
+        removed.push(child.id);
+      }
+    }
+    const db = await this.getDatabase();
+    await new Promise<void>((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], "readwrite");
+      const store = transaction.objectStore(this.storeName);
+      transaction.oncomplete = () => resolve();
+      transaction.onerror = () =>
+        reject(transaction.error ?? new Error("virtual folder delete failed"));
+      transaction.onabort = () =>
+        reject(transaction.error ?? new Error("virtual folder delete aborted"));
+      for (const folderId of removed) store.delete(folderId);
+    });
+    return removed;
+  }
+
+  async clearAll(): Promise<void> {
+    const db = await this.getDatabase();
+    return new Promise((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], "readwrite");
+      const store = transaction.objectStore(this.storeName);
+      const request = store.clear();
+      request.onerror = () => reject(request.error);
+      request.onsuccess = () => resolve();
+    });
+  }
+
+  private async put(record: FolderRecord): Promise<void> {
+    requireVirtualFolder(record);
+    const db = await this.getDatabase();
+    await new Promise<void>((resolve, reject) => {
+      const transaction = db.transaction([this.storeName], "readwrite");
+      const store = transaction.objectStore(this.storeName);
+      const req = store.put(record);
+      req.onerror = () => reject(req.error);
+      req.onsuccess = () => resolve();
+    });
+  }
+
+  /** Walk from `startId` to the root, returning the ids seen. */
+  private async requireWithinDepth(startId: FolderId): Promise<Set<FolderId>> {
+    // One read for the whole store, walked in memory — the chain would
+    // otherwise cost a serialized IndexedDB round trip per ancestor.
+    const byId = new Map(
+      (await this.getAllFolders()).map((folder) => [folder.id, folder]),
+    );
+    const seen = new Set<FolderId>();
+    let cursor: FolderId | null = startId;
+    while (cursor !== null) {
+      if (seen.has(cursor)) {
+        throw new Error("Virtual folder hierarchy contains a cycle");
+      }
+      seen.add(cursor);
+      const parent = byId.get(cursor);
+      if (parent === undefined) {
+        throw new Error(`No virtual folder: ${cursor}`);
+      }
+      cursor = parent.parentFolderId;
+    }
+    // The chain walked is the prospective parent's own ancestry; whatever is
+    // being placed under it sits one level deeper, so a full-depth chain has
+    // no room for a child.
+    if (seen.size >= MAX_FOLDER_DEPTH) {
+      throw new Error(`Folder depth limit reached (max ${MAX_FOLDER_DEPTH})`);
+    }
+    return seen;
+  }
+}
+
+export const virtualFolderStorage = new VirtualFolderStorageService();

frontend/editor/src/core/theme/colors.css

@@ -9,7 +9,7 @@ html[data-app-theme="light"] {
   --c-bg-raised: var(--p-white);
   --c-surface: var(--p-snow);
   --c-surface-raised: var(--p-white);
-  --c-surface-sunken: var(--p-gray-100);
+  --c-surface-sunken: var(--p-c-f0f0f0);
   --c-input-bg: var(--p-white);
   --c-modal-surface: var(--p-white);
   --c-hover: var(--p-gray-50);
@@ -144,7 +144,7 @@ html[data-app-theme="midnight"] {
   --c-bg-raised: var(--p-zinc-850);
   --c-surface: var(--p-c-1a1a1d);
   --c-surface-raised: var(--p-zinc-650);
-  --c-surface-sunken: var(--p-zinc-850);
+  --c-surface-sunken: var(--p-c-100f0e);
   --c-input-bg: var(--c-surface);
   --c-modal-surface: var(--c-surface);
   --c-hover: var(--p-gray-800);
@@ -204,11 +204,8 @@ html[data-app-theme="custom"] {
   --c-bg-raised: color-mix(in srgb, var(--c-primary) 4%, var(--p-white));
   --c-surface: color-mix(in srgb, var(--c-primary) 3%, var(--p-snow));
   --c-surface-raised: color-mix(in srgb, var(--c-primary) 4%, var(--p-white));
-  --c-surface-sunken: color-mix(
-    in srgb,
-    var(--c-primary) 8%,
-    var(--p-gray-100)
-  );
+  /* Neutral recess: no accent mix, so the sunken well stays a plain grey (not cold, not cream). */
+  --c-surface-sunken: var(--p-c-f0f0f0);
   --c-input-bg: color-mix(in srgb, var(--c-primary) 2%, var(--p-white));
   --c-hover: color-mix(in srgb, var(--c-primary) 9%, var(--p-gray-50));
   --c-active: color-mix(in srgb, var(--c-primary) 13%, var(--p-gray-100));
@@ -357,11 +354,8 @@ html[data-app-theme="custom"][data-mantine-color-scheme="dark"] {
     var(--c-primary) 9%,
     var(--p-zinc-775)
   );
-  --c-surface-sunken: color-mix(
-    in srgb,
-    var(--c-primary) 8%,
-    var(--p-zinc-900)
-  );
+  /* Neutral recess (see light): no accent mix, so the sunken well stays a plain near-black. */
+  --c-surface-sunken: var(--p-c-100f0e);
   --c-input-bg: var(--c-surface);
   --c-hover: color-mix(in srgb, var(--c-primary) 12%, var(--p-zinc-750));
   --c-active: color-mix(in srgb, var(--c-primary) 15%, var(--p-zinc-700));
@@ -412,7 +406,7 @@ html[data-app-theme="custom"][data-accent="default"] {
   --c-bg-raised: var(--p-white);
   --c-surface: var(--p-snow);
   --c-surface-raised: var(--p-white);
-  --c-surface-sunken: var(--p-gray-100);
+  --c-surface-sunken: var(--p-c-f0f0f0);
   --c-input-bg: var(--p-white);
   --c-hover: var(--p-gray-50);
   --c-active: var(--p-gray-100);
@@ -425,7 +419,7 @@ html[data-app-theme="custom"][data-accent="default"][data-mantine-color-scheme="
   --c-bg-raised: var(--p-zinc-850);
   --c-surface: var(--p-c-1a1a1d);
   --c-surface-raised: var(--p-zinc-775);
-  --c-surface-sunken: var(--p-zinc-900);
+  --c-surface-sunken: var(--p-c-100f0e);
   --c-input-bg: var(--c-surface);
   --c-hover: var(--p-zinc-750);
   --c-active: var(--p-zinc-700);

frontend/editor/src/core/theme/primitives.css

@@ -39,6 +39,7 @@
   --p-zinc-100: #f4f4f5;
   --p-c-141416: #141416;
   --p-c-1a1a1d: #1a1a1d;
+  --p-c-100f0e: #100f0e;
   --p-c-28282d: #28282d;
   --p-c-343439: #343439;
   --p-blue-400: #60a5fa;

frontend/editor/src/core/types/file.ts

@@ -65,13 +65,16 @@ export interface BaseFileMetadata {
   sourceFileIds?: FileId[];
 
   /**
-   * The cloud folder this file lives in. Semantics:
-   * - `remoteStorageId == null` → file is local-only; folderId MUST be null.
-   * - `remoteStorageId != null && folderId == null` → file is at the cloud root.
-   * - `remoteStorageId != null && folderId == X` → file lives in cloud folder X.
+   * The folder this file lives in. Semantics by storage state:
+   * - Cloud-stored (`remoteStorageId != null`): server-authoritative — null is
+   *   the cloud root, X is server folder X; the sync overwrites it.
+   * - Local-only: browser-owned — a browser folder's id, or the server folder
+   *   the file was placed in at upload time, which membership the server
+   *   adopts once the save-to-server lands (and which keeps the file visibly
+   *   in its folder if that save fails).
    *
-   * The "Local" pseudo-folder in the UI is the predicate `remoteStorageId == null`;
-   * it has no corresponding {@code folderId} value. Folders are a server-only concept.
+   * The "Local" pseudo-folder in the UI is the predicate
+   * `remoteStorageId == null && folderId == null`.
    */
   folderId?: FolderId | null;
 

frontend/editor/src/core/types/folder.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, test } from "vitest";
+import {
+  diskFolderId,
+  diskFolderPath,
+  isDiskFolderId,
+} from "@app/types/folder";
+
+/**
+ * A mount's subdirectories have no stored record, so their ids must carry the
+ * path itself — through a URL, across a reload, for any spelling the OS uses.
+ */
+describe("disk folder ids", () => {
+  test("round-trips Windows, POSIX, and non-ASCII paths", () => {
+    for (const path of [
+      "C:\\Users\\Reece\\Downloads\\Invoices",
+      "/home/reece/Documents/Rechnungen 2026",
+      "D:\\\u041f\u0440\u043e\u0435\u043a\u0442\u044b\\\u0421\u0447\u0435\u0442\u0430",
+    ]) {
+      const id = diskFolderId(path);
+      expect(isDiskFolderId(id)).toBe(true);
+      expect(diskFolderPath(id)).toBe(path);
+    }
+  });
+
+  test("is URL-safe and distinct from stored folder ids", () => {
+    const id = diskFolderId("C:\\a+b/c?d");
+    expect(id).toMatch(/^disk:[A-Za-z0-9_-]+$/);
+    expect(isDiskFolderId("3f0e2a9c-0000-4000-8000-000000000000")).toBe(false);
+    expect(diskFolderPath("not-a-disk-id")).toBeNull();
+  });
+});

frontend/editor/src/core/types/folder.ts

@@ -37,11 +37,21 @@ export const FOLDER_COLOR_PALETTE = [
 /** Members of {@link FOLDER_COLOR_PALETTE}. Use this rather than `string` to keep callers honest. */
 export type FolderPaletteColor = (typeof FOLDER_COLOR_PALETTE)[number];
 
+/**
+ * Three independent features that share a shape, not variants of one: - `server`: in
+ * the server's database, synced down and cached; needs login and storage to exist.
+ */
+export type FolderKind = "server" | "virtual" | "local";
+
 /** Persisted folder shape stored in IndexedDB. */
 export interface FolderRecord {
   id: FolderId;
+  /** Read through {@link folderKind}, never directly. */
+  kind?: FolderKind;
   name: string;
   parentFolderId: FolderId | null;
+  /** For `local` folders: the directory this record mounts. */
+  directory?: string;
   /** Hex colour - either a palette member or any custom hex from a future picker. */
   color?: string;
   icon?: string;
@@ -49,6 +59,11 @@ export interface FolderRecord {
   updatedAt: number;
 }
 
+/** Absent means `server`: server DTOs and rows predating kinds never carry one. */
+export function folderKind(folder: Pick<FolderRecord, "kind">): FolderKind {
+  return folder.kind ?? "server";
+}
+
 /**
  * Folder tree node - derived from FolderRecord[] for rendering the tree
  * navigator. Children are ordered by name (case-insensitive).
@@ -82,6 +97,40 @@ export function parseFolderId(value: unknown): FolderId {
   return value as FolderId;
 }
 
+/** Subdirectories of a mounted folder are not stored anywhere — the directory is the record. */
+const DISK_FOLDER_ID_PREFIX = "disk:";
+
+export function diskFolderId(path: string): FolderId {
+  const bytes = new TextEncoder().encode(path);
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  const b64 = btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+  return `${DISK_FOLDER_ID_PREFIX}${b64}` as FolderId;
+}
+
+export function isDiskFolderId(id: string): boolean {
+  return id.startsWith(DISK_FOLDER_ID_PREFIX);
+}
+
+/** The path a disk subfolder id encodes, or null for any other id. */
+export function diskFolderPath(id: string): string | null {
+  if (!isDiskFolderId(id)) return null;
+  const b64 = id
+    .slice(DISK_FOLDER_ID_PREFIX.length)
+    .replace(/-/g, "+")
+    .replace(/_/g, "/");
+  try {
+    const binary = atob(b64);
+    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+  } catch {
+    return null;
+  }
+}
+
 export function createFolderId(): FolderId {
   return generateId() as FolderId;
 }

frontend/editor/src/core/ui/CardRail.css

@@ -0,0 +1,48 @@
+.sui-card-rail {
+  display: flex;
+  flex-wrap: nowrap;
+  overflow-x: auto;
+  /* A real horizontal scroller: keep the bounce, but don't chain to the browser's back gesture. */
+  overscroll-behavior-x: contain;
+  /* Room for the scrollbar so it doesn't sit under the last row of item content. */
+  padding-bottom: 0.25rem;
+}
+
+/* Gap scale mirrors Stack / Inline. */
+.sui-card-rail--gap-0 {
+  gap: var(--space-0);
+}
+.sui-card-rail--gap-0_5 {
+  gap: var(--space-0_5);
+}
+.sui-card-rail--gap-1 {
+  gap: var(--space-1);
+}
+.sui-card-rail--gap-1_5 {
+  gap: var(--space-1_5);
+}
+.sui-card-rail--gap-2 {
+  gap: var(--space-2);
+}
+.sui-card-rail--gap-3 {
+  gap: var(--space-3);
+}
+.sui-card-rail--gap-4 {
+  gap: var(--space-4);
+}
+.sui-card-rail--gap-5 {
+  gap: var(--space-5);
+}
+.sui-card-rail--gap-6 {
+  gap: var(--space-6);
+}
+.sui-card-rail--gap-8 {
+  gap: var(--space-8);
+}
+
+/* Uniform item sizing: fixed width so items don't stretch/shrink, optional fixed height so a row of
+   cards is equal-height. Both default to natural sizing when the caller sets no dimension. */
+.sui-card-rail > * {
+  flex: 0 0 var(--sui-card-rail-item-w, auto);
+  height: var(--sui-card-rail-item-h, auto);
+}

frontend/editor/src/core/ui/CardRail.stories.tsx

@@ -0,0 +1,69 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import ShieldOutlinedIcon from "@mui/icons-material/ShieldOutlined";
+import CategoryOutlinedIcon from "@mui/icons-material/CategoryOutlined";
+import GavelOutlinedIcon from "@mui/icons-material/GavelOutlined";
+import LayersOutlinedIcon from "@mui/icons-material/LayersOutlined";
+import AltRouteOutlinedIcon from "@mui/icons-material/AltRouteOutlined";
+import ScheduleOutlinedIcon from "@mui/icons-material/ScheduleOutlined";
+import { CardRail } from "@app/ui/CardRail";
+import { OptionCard } from "@app/ui/OptionCard";
+
+const items = [
+  {
+    icon: <ShieldOutlinedIcon />,
+    title: "Security",
+    desc: "Redact, sanitize, and watermark every document.",
+  },
+  {
+    icon: <CategoryOutlinedIcon />,
+    title: "Classification",
+    desc: "Tag each document against your team's labels.",
+  },
+  {
+    icon: <GavelOutlinedIcon />,
+    title: "Compliance",
+    desc: "Enforce frameworks and keep an audit trail.",
+  },
+  {
+    icon: <LayersOutlinedIcon />,
+    title: "Ingestion",
+    desc: "OCR and flatten documents as they arrive.",
+  },
+  {
+    icon: <AltRouteOutlinedIcon />,
+    title: "Routing",
+    desc: "Send finished documents where they belong.",
+  },
+  {
+    icon: <ScheduleOutlinedIcon />,
+    title: "Retention",
+    desc: "Archive and expire on your schedule.",
+  },
+];
+
+const meta: Meta<typeof CardRail> = {
+  title: "Primitives/CardRail",
+  component: CardRail,
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+};
+export default meta;
+type Story = StoryObj<typeof CardRail>;
+
+/** A row of equal-size cards that scrolls sideways when they overflow the container. */
+export const Default: Story = {
+  render: () => (
+    <CardRail itemWidth="16rem" itemHeight="11rem">
+      {items.map((it) => (
+        <OptionCard
+          key={it.title}
+          icon={it.icon}
+          title={it.title}
+          description={it.desc}
+          cta="Set up"
+          onSelect={() => {}}
+        />
+      ))}
+    </CardRail>
+  ),
+};

frontend/editor/src/core/ui/CardRail.tsx

@@ -0,0 +1,56 @@
+import type {
+  CSSProperties,
+  ElementType,
+  HTMLAttributes,
+  ReactNode,
+} from "react";
+import type { StackGap } from "@app/ui/Stack";
+import "@app/ui/CardRail.css";
+
+export interface CardRailProps extends HTMLAttributes<HTMLElement> {
+  /** Token-aligned gap between items (maps to `--space-*`). */
+  gap?: StackGap;
+  /** Fixed width for every item (any CSS length); omit to let items size themselves. */
+  itemWidth?: string;
+  /** Fixed height for every item; omit for natural height. Equal heights line item footers up. */
+  itemHeight?: string;
+  as?: ElementType;
+  children?: ReactNode;
+}
+
+/**
+ * A horizontal row of equal-sized items that scrolls sideways rather than wrapping - the "rail" of
+ * cards motif (template galleries, tier pickers, at-a-glance strips). The scrolling sibling to
+ * {@link Stack} (vertical) and {@link Inline} (horizontal, wraps): it keeps items on one line,
+ * contains the overscroll so it doesn't trigger the browser back-gesture, and sizes every child
+ * uniformly so their footers align.
+ */
+export function CardRail({
+  gap = "3",
+  itemWidth,
+  itemHeight,
+  as,
+  className,
+  style,
+  children,
+  ...rest
+}: CardRailProps) {
+  const Tag: ElementType = as ?? "div";
+  const vars = {
+    ...(itemWidth ? { "--sui-card-rail-item-w": itemWidth } : {}),
+    ...(itemHeight ? { "--sui-card-rail-item-h": itemHeight } : {}),
+    ...style,
+  } as CSSProperties;
+  const classes = [
+    "sui-card-rail",
+    `sui-card-rail--gap-${gap}`,
+    className ?? "",
+  ]
+    .filter(Boolean)
+    .join(" ");
+  return (
+    <Tag className={classes} style={vars} {...rest}>
+      {children}
+    </Tag>
+  );
+}

frontend/editor/src/core/ui/FormField.css

@@ -19,29 +19,7 @@
   color: var(--color-section-label);
 }
 
-/* An (i) affordance beside the label: the explanation lives in its tooltip
-   rather than as permanent subtext under the control. */
-.sui-field__info {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  padding: 0;
-  border: none;
-  background: none;
-  color: var(--c-text-subtle);
-  cursor: pointer;
-  line-height: 0;
-}
-
-.sui-field__info:hover {
-  color: var(--c-text);
-}
-
-.sui-field__info:focus-visible {
-  outline: 2px solid var(--c-primary);
-  outline-offset: 2px;
-  border-radius: 999px;
-}
+/* The label's (i) affordance is the shared InfoTooltip primitive (@app/ui/InfoTooltip). */
 
 .sui-field__required {
   /* The base red is a fill colour; as text on the form background it only

frontend/editor/src/core/ui/FormField.tsx

@@ -5,7 +5,7 @@ import {
   type ReactElement,
   type ReactNode,
 } from "react";
-import { Tooltip } from "@mantine/core";
+import { InfoTooltip } from "@app/ui/InfoTooltip";
 import "@app/ui/FormField.css";
 
 export interface FormFieldProps {
@@ -77,40 +77,7 @@ export function FormField({
               )}
             </label>
           )}
-          {info && (
-            <Tooltip
-              label={info}
-              multiline
-              w={260}
-              withArrow
-              position="top"
-              events={{ hover: true, focus: true, touch: true }}
-            >
-              <button
-                type="button"
-                className="sui-field__info"
-                aria-label={
-                  typeof info === "string" ? info : "More information"
-                }
-              >
-                <svg
-                  viewBox="0 0 24 24"
-                  width="14"
-                  height="14"
-                  fill="none"
-                  stroke="currentColor"
-                  strokeWidth={2}
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  aria-hidden
-                >
-                  <circle cx="12" cy="12" r="10" />
-                  <line x1="12" y1="16" x2="12" y2="12" />
-                  <line x1="12" y1="8" x2="12.01" y2="8" />
-                </svg>
-              </button>
-            </Tooltip>
-          )}
+          {info && <InfoTooltip label={info} />}
         </div>
       )}
       <div className="sui-field__control">{child}</div>

frontend/editor/src/core/ui/IconPicker.css

@@ -0,0 +1,31 @@
+.sui-icon-picker__grid {
+  display: grid;
+  grid-template-columns: repeat(5, 2.25rem);
+  gap: 0.25rem;
+  padding: 0.375rem;
+}
+
+.sui-icon-picker__option {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.25rem;
+  height: 2.25rem;
+  border: 1px solid transparent;
+  border-radius: var(--radius-md);
+  background: transparent;
+  color: var(--c-text-muted);
+  cursor: pointer;
+}
+
+.sui-icon-picker__option:hover {
+  background: var(--c-hover);
+  color: var(--c-text);
+}
+
+.sui-icon-picker__option--selected {
+  border-color: var(--c-primary);
+  background: var(--c-primary-subtle);
+  /* Accent tuned to clear the contrast floor on the tinted chip (light + dark). */
+  color: var(--c-accent-text);
+}

frontend/editor/src/core/ui/IconPicker.stories.tsx

@@ -0,0 +1,55 @@
+import { useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import ShieldOutlinedIcon from "@mui/icons-material/ShieldOutlined";
+import LockOutlinedIcon from "@mui/icons-material/LockOutlined";
+import LabelOutlinedIcon from "@mui/icons-material/LabelOutlined";
+import LayersOutlinedIcon from "@mui/icons-material/LayersOutlined";
+import FolderOutlinedIcon from "@mui/icons-material/FolderOutlined";
+import BoltOutlinedIcon from "@mui/icons-material/BoltOutlined";
+import ScheduleOutlinedIcon from "@mui/icons-material/ScheduleOutlined";
+import AutoAwesomeOutlinedIcon from "@mui/icons-material/AutoAwesomeOutlined";
+import { IconPicker, type IconPickerOption } from "@app/ui/IconPicker";
+
+const sx = { fontSize: "1.25rem" } as const;
+const OPTIONS: IconPickerOption[] = [
+  { key: "shield", label: "Shield", node: <ShieldOutlinedIcon sx={sx} /> },
+  { key: "lock", label: "Lock", node: <LockOutlinedIcon sx={sx} /> },
+  { key: "label", label: "Label", node: <LabelOutlinedIcon sx={sx} /> },
+  { key: "layers", label: "Layers", node: <LayersOutlinedIcon sx={sx} /> },
+  { key: "folder", label: "Folder", node: <FolderOutlinedIcon sx={sx} /> },
+  { key: "bolt", label: "Bolt", node: <BoltOutlinedIcon sx={sx} /> },
+  {
+    key: "schedule",
+    label: "Schedule",
+    node: <ScheduleOutlinedIcon sx={sx} />,
+  },
+  {
+    key: "sparkle",
+    label: "Sparkle",
+    node: <AutoAwesomeOutlinedIcon sx={sx} />,
+  },
+];
+
+const meta: Meta<typeof IconPicker> = {
+  title: "Primitives/IconPicker",
+  component: IconPicker,
+  tags: ["autodocs"],
+  parameters: { layout: "centered" },
+};
+export default meta;
+type Story = StoryObj<typeof IconPicker>;
+
+/** Click the glyph to open the grid and choose a new icon from the supplied set. */
+export const Default: Story = {
+  render: () => {
+    const [value, setValue] = useState("shield");
+    return (
+      <IconPicker
+        value={value}
+        onChange={setValue}
+        options={OPTIONS}
+        ariaLabel="Icon"
+      />
+    );
+  },
+};

frontend/editor/src/core/ui/IconPicker.tsx

@@ -0,0 +1,78 @@
+import { useState, type ReactNode } from "react";
+import { ActionIcon } from "@app/ui/ActionIcon";
+import { Dropdown } from "@app/ui/Dropdown";
+import "@app/ui/IconPicker.css";
+
+export interface IconPickerOption {
+  /** Stable identifier stored as the picked value. */
+  key: string;
+  /** The glyph to show, sized by the caller. */
+  node: ReactNode;
+  /** Accessible name for this option (falls back to the key). */
+  label?: string;
+}
+
+export interface IconPickerProps {
+  /** The picked option's key. */
+  value: string;
+  onChange: (key: string) => void;
+  /** The icons to choose from, in display order. The caller supplies the set. */
+  options: IconPickerOption[];
+  /** Accessible name for the trigger (e.g. "Icon"). */
+  ariaLabel: string;
+  size?: "sm" | "md" | "lg";
+}
+
+/**
+ * Pick an icon from a caller-supplied set. The chosen glyph is the trigger; the menu is a grid. The
+ * icon set is injected (via {@link options}) rather than baked in, so any surface - a pipeline, a
+ * watched folder, an automation - passes its own vocabulary and shares the one control.
+ */
+export function IconPicker({
+  value,
+  onChange,
+  options,
+  ariaLabel,
+  size = "sm",
+}: IconPickerProps) {
+  // Controlled so a grid button (not a Dropdown.Item) can close the menu on pick.
+  const [open, setOpen] = useState(false);
+  const selected = options.find((option) => option.key === value) ?? options[0];
+
+  function pick(key: string) {
+    onChange(key);
+    setOpen(false);
+  }
+
+  return (
+    <Dropdown.Root open={open} onOpenChange={setOpen} align="start">
+      <Dropdown.Trigger>
+        <ActionIcon variant="secondary" size={size} aria-label={ariaLabel}>
+          {selected?.node}
+        </ActionIcon>
+      </Dropdown.Trigger>
+      <Dropdown.Menu>
+        <div className="sui-icon-picker__grid">
+          {options.map((option) => {
+            const isSelected = option.key === value;
+            return (
+              <button
+                key={option.key}
+                type="button"
+                className={
+                  "sui-icon-picker__option" +
+                  (isSelected ? " sui-icon-picker__option--selected" : "")
+                }
+                aria-label={option.label ?? option.key}
+                aria-pressed={isSelected}
+                onClick={() => pick(option.key)}
+              >
+                {option.node}
+              </button>
+            );
+          })}
+        </div>
+      </Dropdown.Menu>
+    </Dropdown.Root>
+  );
+}

frontend/editor/src/core/ui/InfoTooltip.css

@@ -0,0 +1,19 @@
+.sui-info {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: none;
+  background: none;
+  color: var(--c-text-subtle);
+  cursor: pointer;
+  line-height: 0;
+}
+.sui-info:hover {
+  color: var(--c-text);
+}
+.sui-info:focus-visible {
+  outline: 2px solid var(--c-primary);
+  outline-offset: 2px;
+  border-radius: 999px;
+}

frontend/editor/src/core/ui/InfoTooltip.stories.tsx

@@ -0,0 +1,30 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { InfoTooltip } from "@app/ui/InfoTooltip";
+
+const meta: Meta<typeof InfoTooltip> = {
+  title: "Primitives/InfoTooltip",
+  component: InfoTooltip,
+  tags: ["autodocs"],
+  parameters: { layout: "centered" },
+  args: {
+    label: "The folder (key prefix) within the bucket to watch.",
+    position: "top",
+  },
+};
+export default meta;
+type Story = StoryObj<typeof InfoTooltip>;
+
+/** Hover or focus the (i) to reveal the explanation. */
+export const Default: Story = {};
+
+/** Inline beside a label, the way FormField renders it. */
+export const BesideLabel: Story = {
+  render: (args) => (
+    <span
+      style={{ display: "inline-flex", alignItems: "center", gap: "0.25rem" }}
+    >
+      <span style={{ fontSize: "0.8125rem", fontWeight: 600 }}>Folder</span>
+      <InfoTooltip {...args} />
+    </span>
+  ),
+};

frontend/editor/src/core/ui/InfoTooltip.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react";
+import { Tooltip, type FloatingPosition } from "@mantine/core";
+import "@app/ui/InfoTooltip.css";
+
+export interface InfoTooltipProps {
+  /** The explanation shown in the tooltip on hover/focus. */
+  label: ReactNode;
+  /** Accessible name for the button. Defaults to the label when it's a string. */
+  ariaLabel?: string;
+  /** Which side the tooltip opens on. Default "top". */
+  position?: FloatingPosition;
+}
+
+/**
+ * The app's standard inline info affordance: a small, muted (i) that reveals supplementary text in a
+ * hover/focus tooltip, without taking permanent space. Used behind form labels ({@link FormField})
+ * and anywhere a control needs a hint - one implementation so every (i) reads and behaves the same.
+ */
+export function InfoTooltip({
+  label,
+  ariaLabel,
+  position = "top",
+}: InfoTooltipProps) {
+  return (
+    <Tooltip
+      label={label}
+      multiline
+      w={260}
+      withArrow
+      position={position}
+      events={{ hover: true, focus: true, touch: true }}
+    >
+      <button
+        type="button"
+        className="sui-info"
+        aria-label={
+          ariaLabel ?? (typeof label === "string" ? label : "More information")
+        }
+      >
+        <svg
+          viewBox="0 0 24 24"
+          width="14"
+          height="14"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden
+        >
+          <circle cx="12" cy="12" r="10" />
+          <line x1="12" y1="16" x2="12" y2="12" />
+          <line x1="12" y1="8" x2="12.01" y2="8" />
+        </svg>
+      </button>
+    </Tooltip>
+  );
+}

frontend/editor/src/core/ui/OptionCard.css

@@ -0,0 +1,84 @@
+.sui-option-card {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.5rem;
+  /* Fill whatever height the parent row establishes, so footers align across a row of cards. */
+  height: 100%;
+}
+
+/* Icon and title share a row. */
+.sui-option-card__head {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+}
+
+.sui-option-card__icon {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  width: 2.25rem;
+  height: 2.25rem;
+  border-radius: var(--radius-md);
+  background: var(--c-primary-subtle);
+  color: var(--c-accent-fg, var(--c-primary));
+}
+
+.sui-option-card__title {
+  margin: 0;
+  font-size: 0.9375rem;
+  font-weight: 640;
+  color: var(--c-text);
+}
+
+.sui-option-card__desc {
+  margin: 0;
+  font-size: 0.8125rem;
+  line-height: 1.45;
+  color: var(--c-text-subtle);
+  /* Clamp long descriptions with a trailing ellipsis. No flex-grow: stretching the box defeats
+     -webkit-line-clamp and hard-clips mid-word instead. */
+  overflow: hidden;
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: var(--sui-option-card-lines, 3);
+}
+
+/* Pin whatever ends the card (the CTA or a note) to the foot, so footers line up across cards
+   without flex-growing the clamped blurb above. */
+.sui-option-card > :last-child {
+  margin-top: auto;
+}
+
+.sui-option-card__foot {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+  font-size: 0.8125rem;
+  font-weight: 620;
+  /* Accent text tuned to clear the contrast floor on the card surface (light + dark), unlike raw
+     --c-primary which is too light for small text. */
+  color: var(--c-accent-text);
+}
+
+/* Disabled cards recede onto the sunken surface: every label goes muted so the card reads clearly
+   greyed against the usable ones, while the icon keeps a faint raised chip in its own colour so it
+   stays distinct from the greyed text rather than flattening into it. */
+.sui-option-card--disabled {
+  background: var(--c-surface-sunken);
+  cursor: default;
+}
+
+.sui-option-card--disabled .sui-option-card__icon {
+  background: var(--c-surface);
+  color: var(--c-text-subtle);
+}
+
+.sui-option-card--disabled .sui-option-card__title,
+.sui-option-card--disabled .sui-option-card__desc,
+.sui-option-card--disabled .sui-option-card__foot {
+  color: var(--c-text-muted);
+  font-weight: 600;
+}

frontend/editor/src/core/ui/OptionCard.stories.tsx

@@ -0,0 +1,103 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import ShieldOutlinedIcon from "@mui/icons-material/ShieldOutlined";
+import CategoryOutlinedIcon from "@mui/icons-material/CategoryOutlined";
+import GavelOutlinedIcon from "@mui/icons-material/GavelOutlined";
+import ArrowForwardRoundedIcon from "@mui/icons-material/ArrowForwardRounded";
+import LockOutlinedIcon from "@mui/icons-material/LockOutlined";
+import { OptionCard } from "@app/ui/OptionCard";
+
+const setUp = (
+  <>
+    Set up
+    <ArrowForwardRoundedIcon style={{ fontSize: "1rem" }} />
+  </>
+);
+
+const comingSoon = (
+  <>
+    <LockOutlinedIcon style={{ fontSize: "0.95rem" }} />
+    Coming soon
+  </>
+);
+
+const meta: Meta<typeof OptionCard> = {
+  title: "Primitives/OptionCard",
+  component: OptionCard,
+  tags: ["autodocs"],
+  parameters: { layout: "padded" },
+  args: {
+    icon: <ShieldOutlinedIcon />,
+    title: "Security",
+    description:
+      "Redact sensitive information, strip active content, and watermark every document.",
+    cta: setUp,
+    disabled: false,
+    onSelect: () => {},
+  },
+  argTypes: {
+    icon: { control: false },
+    cta: { control: false },
+    note: { control: false },
+    onSelect: { control: false },
+    descriptionLines: { control: { type: "number", min: 1, max: 6 } },
+  },
+  decorators: [
+    (S) => (
+      <div style={{ width: "16rem", height: "12rem" }}>
+        <S />
+      </div>
+    ),
+  ],
+};
+export default meta;
+type Story = StoryObj<typeof OptionCard>;
+
+/** Toggle `disabled`, edit the title/description, change the clamp in controls. */
+export const Playground: Story = {};
+
+/** Inert: no click or hover, muted, with a note in place of the CTA. */
+export const Disabled: Story = {
+  args: { disabled: true, note: comingSoon },
+};
+
+/** The gallery use case: a row of selectable options with one disabled. */
+export const Gallery: Story = {
+  decorators: [
+    (S) => (
+      <div style={{ width: "100%" }}>
+        <S />
+      </div>
+    ),
+  ],
+  render: () => (
+    <div style={{ display: "flex", gap: "0.75rem", height: "12rem" }}>
+      <div style={{ flex: "0 0 16rem" }}>
+        <OptionCard
+          icon={<ShieldOutlinedIcon />}
+          title="Security"
+          description="Redact sensitive information, strip active content, and watermark every document."
+          cta={setUp}
+          onSelect={() => {}}
+        />
+      </div>
+      <div style={{ flex: "0 0 16rem" }}>
+        <OptionCard
+          icon={<CategoryOutlinedIcon />}
+          title="Classification"
+          description="Identify each document's type against your team's labels and tag it automatically."
+          cta={setUp}
+          onSelect={() => {}}
+        />
+      </div>
+      <div style={{ flex: "0 0 16rem" }}>
+        <OptionCard
+          icon={<GavelOutlinedIcon />}
+          title="Compliance"
+          description="Enforce your regulatory frameworks and keep an audit trail of every change."
+          disabled
+          note={comingSoon}
+        />
+      </div>
+    </div>
+  ),
+};

frontend/editor/src/core/ui/OptionCard.tsx

@@ -0,0 +1,84 @@
+import type { CSSProperties, KeyboardEvent, ReactNode } from "react";
+import { Card } from "@app/ui/Card";
+import "@app/ui/OptionCard.css";
+
+export interface OptionCardProps {
+  /** Leading glyph, shown in a tinted chip. */
+  icon: ReactNode;
+  title: ReactNode;
+  /** Short blurb under the title; clamped to {@link descriptionLines} lines. */
+  description?: ReactNode;
+  /**
+   * Footer shown when the card is selectable - typically a call to action like "Set up ->". Pinned
+   * to the bottom edge so footers line up across a row of cards.
+   */
+  cta?: ReactNode;
+  /**
+   * When true the card is inert (no click, no hover) and recedes to a muted, sunken treatment.
+   * {@link note} replaces the CTA to say why (e.g. a "coming soon" or lock chip).
+   */
+  disabled?: boolean;
+  note?: ReactNode;
+  /** Lines the description clamps to before ellipsis. Default 3. */
+  descriptionLines?: number;
+  /** Fires when a selectable card is clicked or activated by keyboard. Ignored when disabled. */
+  onSelect?: () => void;
+  className?: string;
+}
+
+/**
+ * A choice presented as a titled card: a tinted icon chip, a title, a clamped blurb, and a footer (a
+ * CTA when selectable, a muted note when not). A primitive for the recurring "pick one of these"
+ * motif (template galleries, feature pickers) so its layout, disabled treatment and select a11y are
+ * shared rather than re-styled per feature.
+ */
+export function OptionCard({
+  icon,
+  title,
+  description,
+  cta,
+  disabled = false,
+  note,
+  descriptionLines = 3,
+  onSelect,
+  className,
+}: OptionCardProps) {
+  const interactive = !disabled && !!onSelect;
+
+  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      onSelect?.();
+    }
+  }
+
+  return (
+    <Card
+      interactive={interactive}
+      className={[
+        "sui-option-card",
+        disabled ? "sui-option-card--disabled" : "",
+        className ?? "",
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      style={{ "--sui-option-card-lines": descriptionLines } as CSSProperties}
+      onClick={interactive ? onSelect : undefined}
+      role={interactive ? "button" : undefined}
+      tabIndex={interactive ? 0 : undefined}
+      onKeyDown={interactive ? onKeyDown : undefined}
+      aria-disabled={disabled || undefined}
+    >
+      <div className="sui-option-card__head">
+        <span className="sui-option-card__icon" aria-hidden>
+          {icon}
+        </span>
+        <h3 className="sui-option-card__title">{title}</h3>
+      </div>
+      {description && <p className="sui-option-card__desc">{description}</p>}
+      {(disabled ? note : cta) && (
+        <span className="sui-option-card__foot">{disabled ? note : cta}</span>
+      )}
+    </Card>
+  );
+}

frontend/editor/src/core/ui/index.ts

@@ -10,6 +10,10 @@ export * from "@app/ui/ToggleSwitch";
 export * from "@app/ui/ProgressBar";
 export * from "@app/ui/MetricCard";
 export * from "@app/ui/NodeCard";
+export * from "@app/ui/OptionCard";
+export * from "@app/ui/CardRail";
+export * from "@app/ui/IconPicker";
+export * from "@app/ui/InfoTooltip";
 export * from "@app/ui/NavItem";
 export * from "@app/ui/NavSurface";
 export * from "@app/ui/Surface";

frontend/editor/src/desktop/components/AppProviders.tsx

@@ -1,6 +1,7 @@
 import { ReactNode, useEffect, useRef, useState } from "react";
 import { AppProviders as ProprietaryAppProviders } from "@proprietary/components/AppProviders";
 import { DesktopConfigSync } from "@app/components/DesktopConfigSync";
+import { WindowTitleBar } from "@app/components/WindowTitleBar";
 import { DesktopQueryCacheReset } from "@app/components/DesktopQueryCacheReset";
 import { DesktopBannerInitializer } from "@app/components/DesktopBannerInitializer";
 import { SaveShortcutListener } from "@app/components/SaveShortcutListener";
@@ -328,6 +329,7 @@ export function AppProviders({ children }: { children: ReactNode }) {
       >
         {/* Also here: the auth check below switches mode pre-authChecked. */}
         <DesktopQueryCacheReset />
+        <WindowTitleBar />
         <div style={{ minHeight: "100vh" }} />
         {updatePopupModal}
       </ProprietaryAppProviders>
@@ -354,6 +356,7 @@ export function AppProviders({ children }: { children: ReactNode }) {
         }}
       >
         <DesktopQueryCacheReset />
+        <WindowTitleBar />
         <SaaSTeamProvider key={appKey}>
           <DesktopConfigSync />
           <DesktopBannerInitializer />

frontend/editor/src/desktop/components/WindowTitleBar.module.css

@@ -0,0 +1,58 @@
+/* Custom Windows window controls (see WindowTitleBar.tsx): a fixed cluster in
+   the top-right corner, overlaying the app chrome — which reserves the corner
+   via --wincontrols-w. Kept above app overlays so the controls stay usable. */
+.titleBar {
+  position: fixed;
+  top: 0;
+  right: 0;
+  z-index: 1500;
+  display: flex;
+  height: 2rem;
+  user-select: none;
+  -webkit-user-select: none;
+}
+
+.controls {
+  display: flex;
+  align-items: stretch;
+  height: 100%;
+}
+
+.button {
+  width: 46px;
+  height: 100%;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: none;
+  background: transparent;
+  color: var(--c-text-muted);
+  font-size: 15px; /* drives the inherit-sized MUI icons */
+  line-height: 1;
+  cursor: default;
+  transition:
+    background-color 0.12s ease,
+    color 0.12s ease;
+}
+
+/* Clicks (and Tauri's drag-region hit test) should always resolve to the
+   button, never its SVG glyph. */
+.button svg {
+  pointer-events: none;
+}
+
+.button:hover {
+  background: var(--c-hover);
+  color: var(--c-text);
+}
+
+.close:hover {
+  background: var(--c-danger);
+  color: #fff;
+}
+
+.restoreIcon {
+  /* The overlapping-squares glyph reads large next to the others. */
+  font-size: 13px;
+}

frontend/editor/src/desktop/components/WindowTitleBar.tsx

@@ -0,0 +1,187 @@
+import { useEffect, useState } from "react";
+import { useIsomorphicEffect } from "@mantine/hooks";
+import { getCurrentWindow } from "@tauri-apps/api/window";
+import { isTauri } from "@tauri-apps/api/core";
+import MinimizeIcon from "@mui/icons-material/Minimize";
+import CropSquareIcon from "@mui/icons-material/CropSquare";
+import FilterNoneIcon from "@mui/icons-material/FilterNone";
+import CloseIcon from "@mui/icons-material/Close";
+import { getDesktopOs, DesktopOs } from "@app/services/platformService";
+import styles from "@app/components/WindowTitleBar.module.css";
+// Desktop-only skin that reserves the controls' corner across core layout
+// surfaces; every rule is gated by the data-window-controls flag set below.
+import "@app/components/windowChrome.css";
+
+// Seed from the UA so the bar (and its reserved height) is present on the first
+// frame on Windows, avoiding a layout shift. getDesktopOs() confirms it right
+// after via the Rust command.
+const seedIsWindows =
+  typeof navigator !== "undefined" && /Windows/i.test(navigator.userAgent);
+
+/**
+ * Custom window controls for the Windows desktop build. The native caption is
+ * removed in Rust (decorations:false), so this draws minimize/maximize/close as
+ * a fixed overlay pinned to the top-right corner — the rail and panels run all
+ * the way to the window edge, and the app chrome reserves the corner via the
+ * data-window-controls flag this sets on <html> (consumed by windowChrome.css).
+ * Renders nothing on macOS/Linux (native decorations kept); not bundled in the
+ * browser build. tao provides edge/corner resize for the undecorated window, so
+ * no manual resize handles are needed here.
+ */
+export function WindowTitleBar() {
+  const [isWindows, setIsWindows] = useState(seedIsWindows);
+  const [maximized, setMaximized] = useState(false);
+  const active = isWindows && isTauri();
+
+  // Confirm the OS authoritatively (the UA seed is only a first-frame guess).
+  useEffect(() => {
+    if (!isTauri()) {
+      setIsWindows(false);
+      return;
+    }
+    let mounted = true;
+    void getDesktopOs().then((os) => {
+      if (mounted) setIsWindows(os === DesktopOs.Windows);
+    });
+    return () => {
+      mounted = false;
+    };
+  }, []);
+
+  // Flag the custom chrome on <html> so windowChrome.css can reserve the
+  // controls' corner across the app. Set only when active (Windows desktop);
+  // absent otherwise, so the skin is inert on macOS/Linux. Layout effect so it
+  // lands before paint.
+  useIsomorphicEffect(() => {
+    const root = document.documentElement;
+    if (active) {
+      root.setAttribute("data-window-controls", "custom");
+    } else {
+      root.removeAttribute("data-window-controls");
+    }
+    return () => {
+      root.removeAttribute("data-window-controls");
+    };
+  }, [active]);
+
+  // Keep the maximize/restore icon in sync with the actual window state
+  // (double-click, snap, or the button itself all change it).
+  useEffect(() => {
+    if (!active) return;
+    const appWindow = getCurrentWindow();
+    let unlisten: (() => void) | undefined;
+    void appWindow.isMaximized().then(setMaximized);
+    void appWindow
+      .onResized(() => {
+        void appWindow.isMaximized().then(setMaximized);
+      })
+      .then((u) => {
+        unlisten = u;
+      });
+    return () => unlisten?.();
+  }, [active]);
+
+  // Let the window be dragged, and double-click-maximized, from any
+  // non-interactive spot in the top strip. data-tauri-drag-region only fires on
+  // bare container backgrounds, leaving most of a busy toolbar undraggable, so a
+  // document-level hit test covers the whole top instead.
+  //
+  // startDragging() must NOT run on mousedown: it enters the OS drag loop and
+  // swallows the browser's dblclick. So begin the drag on the first real move,
+  // and detect a double-click from the interval between mousedowns.
+  useEffect(() => {
+    if (!active) return;
+    const TOP_STRIP_PX = 48;
+    const DOUBLE_CLICK_MS = 500;
+    const DRAG_THRESHOLD_PX = 4;
+    const INTERACTIVE =
+      "button, a[href], input, textarea, select, label, summary," +
+      '[role="button"], [role="tab"], [role="menuitem"], [role="switch"],' +
+      '[role="slider"], [contenteditable="true"], [data-no-window-drag]';
+    const draggableAt = (e: MouseEvent) => {
+      if (e.button !== 0 || e.clientY > TOP_STRIP_PX) return false;
+      const el = e.target as Element | null;
+      return !!el && !el.closest(INTERACTIVE);
+    };
+    let pending: { x: number; y: number } | null = null;
+    let lastDownAt = 0;
+    const onMouseDown = (e: MouseEvent) => {
+      if (!draggableAt(e)) {
+        pending = null;
+        return;
+      }
+      const now = Date.now();
+      if (now - lastDownAt < DOUBLE_CLICK_MS) {
+        pending = null;
+        lastDownAt = 0;
+        void getCurrentWindow().toggleMaximize();
+        return;
+      }
+      lastDownAt = now;
+      pending = { x: e.clientX, y: e.clientY };
+    };
+    const onMouseMove = (e: MouseEvent) => {
+      if (!pending) return;
+      if (
+        Math.abs(e.clientX - pending.x) > DRAG_THRESHOLD_PX ||
+        Math.abs(e.clientY - pending.y) > DRAG_THRESHOLD_PX
+      ) {
+        pending = null;
+        lastDownAt = 0; // a drag is not the first half of a double-click
+        void getCurrentWindow().startDragging();
+      }
+    };
+    const onMouseUp = () => {
+      pending = null;
+    };
+    document.addEventListener("mousedown", onMouseDown);
+    document.addEventListener("mousemove", onMouseMove);
+    document.addEventListener("mouseup", onMouseUp);
+    return () => {
+      document.removeEventListener("mousedown", onMouseDown);
+      document.removeEventListener("mousemove", onMouseMove);
+      document.removeEventListener("mouseup", onMouseUp);
+    };
+  }, [active]);
+
+  if (!active) return null;
+
+  const appWindow = getCurrentWindow();
+  return (
+    <div className={styles.titleBar}>
+      <div className={styles.controls}>
+        <button
+          type="button"
+          className={styles.button}
+          onClick={() => void appWindow.minimize()}
+          aria-label="Minimize"
+          tabIndex={-1}
+        >
+          <MinimizeIcon fontSize="inherit" />
+        </button>
+        <button
+          type="button"
+          className={styles.button}
+          onClick={() => void appWindow.toggleMaximize()}
+          aria-label={maximized ? "Restore" : "Maximize"}
+          tabIndex={-1}
+        >
+          {maximized ? (
+            <FilterNoneIcon fontSize="inherit" className={styles.restoreIcon} />
+          ) : (
+            <CropSquareIcon fontSize="inherit" />
+          )}
+        </button>
+        <button
+          type="button"
+          className={`${styles.button} ${styles.close}`}
+          onClick={() => void appWindow.close()}
+          aria-label="Close"
+          tabIndex={-1}
+        >
+          <CloseIcon fontSize="inherit" />
+        </button>
+      </div>
+    </div>
+  );
+}

frontend/editor/src/desktop/components/windowChrome.css

@@ -0,0 +1,55 @@
+/* Desktop (Windows) custom window chrome.
+ *
+ * The window controls are a fixed overlay in the top-right corner (see
+ * WindowTitleBar). These rules keep the app's own chrome clear of that corner.
+ *
+ * Loaded only in the desktop build (imported by WindowTitleBar) and gated on the
+ * data-window-controls flag the overlay sets on <html> only when active, so it
+ * is inert on macOS/Linux (flag never set) and absent from web builds. It
+ * targets core layout class names on purpose: this is the single, contained
+ * coupling point between the desktop chrome and the core layout, kept here in
+ * the desktop layer so the core components stay unaware of window chrome. */
+
+html[data-window-controls="custom"] {
+  --wincontrols-w: 8.625rem; /* three 46px controls */
+  --wincontrols-h: 2rem; /* control height */
+}
+
+/* Files-page toolbar spans the width; reflow search + actions left of the
+   controls by shrinking the grid's right edge. */
+html[data-window-controls="custom"] .files-page-header {
+  padding-right: calc(0.75rem + var(--wincontrols-w));
+}
+
+/* Right panel, expanded: move the header (PDF Tools, or an active tool such as
+   Automate) below the controls instead of squashing its title. */
+html[data-window-controls="custom"] .tool-panel__compact-header,
+html[data-window-controls="custom"] .tool-panel .sui-panelhdr {
+  margin-top: var(--wincontrols-h);
+}
+
+/* Right panel, collapsed: the strip is narrower than the controls, so push its
+   expand toggle straight down. */
+html[data-window-controls="custom"] .tool-panel__collapsed-strip {
+  padding-top: calc(10px + var(--wincontrols-h));
+}
+
+/* Viewer top bar: when the right panel is collapsed the bar widens under the
+   controls. :has() detects the collapsed strip (no flag needed in core) and we
+   push the right cluster clear. --nav-rail-w is the collapsed strip's width, so
+   only the controls' overhang past it is reserved. */
+html[data-window-controls="custom"]
+  .app-frame__content:has(.tool-panel__collapsed-strip)
+  .workbench-bar-globals {
+  margin-right: calc(var(--wincontrols-w) - var(--nav-rail-w));
+}
+
+/* Mobile layout: the top bar spans the full width. Keep the brand top-left
+   (already clear of the top-right controls) and drop the view switcher below
+   them by top-aligning the row and nudging the switcher down. */
+html[data-window-controls="custom"] .mobile-toggle {
+  align-items: flex-start;
+}
+html[data-window-controls="custom"] .mobile-toggle-buttons {
+  margin-top: var(--wincontrols-h);
+}

frontend/editor/src/desktop/hooks/useServerFolderBlock.ts

@@ -0,0 +1,43 @@
+import { useEffect, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { connectionModeService } from "@app/services/connectionModeService";
+import type { ConnectionMode } from "@app/services/connectionModeService";
+import { useServerFolderBlock as useCoreServerFolderBlock } from "@core/hooks/useServerFolderBlock";
+
+/**
+ * Desktop's blocker speaks in connection modes: local mode has no server at all, so
+ * "storage isn't enabled" would send the user after a setting that does not exist.
+ */
+export function useServerFolderBlock(): string | null {
+  const { t } = useTranslation();
+  const coreReason = useCoreServerFolderBlock();
+  // Seeded from the cache so a remount answers on its first frame; the effect covers
+  // the first-ever load and later mode switches.
+  const [mode, setMode] = useState<ConnectionMode | null>(() =>
+    connectionModeService.getCachedMode(),
+  );
+  useEffect(() => {
+    let mounted = true;
+    void connectionModeService.getCurrentMode().then((current) => {
+      if (mounted) setMode(current);
+    });
+    const unsubscribe = connectionModeService.subscribeToModeChanges((config) =>
+      setMode(config.mode),
+    );
+    return () => {
+      mounted = false;
+      unsubscribe();
+    };
+  }, []);
+  // While the mode is unknown (first-ever load), fail closed with the same message: in
+  // any mode where the item would be blocked, signing in or connecting a server IS the
+  // way out — unlike the core reasons, which in local mode point at a storage setting
+  // that doesn't exist.
+  if (mode === "local" || mode === null) {
+    return t(
+      "filesPage.serverFolderNeedsConnection",
+      "Sign in to Stirling Cloud or connect a self-hosted server to use server folders.",
+    );
+  }
+  return coreReason;
+}

frontend/editor/src/desktop/services/connectionModeService.ts

@@ -71,6 +71,11 @@ export class ConnectionModeService {
     return config.mode;
   }
 
+  /** The mode already in memory, or null before the first load. */
+  getCachedMode(): ConnectionMode | null {
+    return this.currentConfig?.mode ?? null;
+  }
+
   async getServerConfig(): Promise<ServerConfig | null> {
     const config = await this.getCurrentConfig();
     return config.server_config;