text fixing

Merge remote-tracking branch 'origin/V2' into latex2
Print with embed (#5109 )
2025-12-03 10:48:13 +00:00 · 2025-12-03 09:07:42 +00:00 · 2025-12-02 13:56:28 +00:00 · 2025-12-02 12:40:20 +00:00 · 2025-12-02 12:34:38 +00:00 · 2025-12-02 12:34:17 +00:00
116 changed files with 1966 additions and 2377 deletions
@@ -31,12 +31,10 @@ import stirling.software.common.model.api.PDFFile;
 import stirling.software.common.service.JobOwnershipService;
 import stirling.software.common.util.ExceptionUtils;
 import stirling.software.common.util.WebResponseUtils;
-import stirling.software.proprietary.security.config.PremiumEndpoint;

@Slf4j
@ConvertApi
@RequiredArgsConstructor
-@PremiumEndpoint
 public class ConvertPdfJsonController {

    private final PdfJsonConversionService pdfJsonConversionService;
@@ -19,9 +19,9 @@ import stirling.software.common.service.UserServiceInterface;

 /**
 * Unified signature image controller that works for both authenticated and unauthenticated users.
- * Uses composition pattern: - Core SharedSignatureService (always available): reads shared signatures -
- * PersonalSignatureService (proprietary, optional): reads personal signatures For authenticated
- * signature management (save/delete), see proprietary SignatureController.
+ * Uses composition pattern: - Core SharedSignatureService (always available): reads shared
+ * signatures - PersonalSignatureService (proprietary, optional): reads personal signatures For
+ * authenticated signature management (save/delete), see proprietary SignatureController.
 */
@Slf4j
@RestController
@@ -283,7 +283,12 @@ public class AdminLicenseController {
        // Prevent path traversal and enforce single filename component
        if (filename.contains("..") || filename.contains("/") || filename.contains("\\")) {
            return ResponseEntity.badRequest()
-                    .body(Map.of("success", false, "error", "Filename must not contain path separators or '..'"));
+                    .body(
+                            Map.of(
+                                    "success",
+                                    false,
+                                    "error",
+                                    "Filename must not contain path separators or '..'"));
        }

        // Validate file extension
@@ -56,6 +56,19 @@ public interface UserRepository extends JpaRepository<User, Long> {
                    + "OR LOWER(u.authenticationType) IN ('sso', 'oauth2', 'saml2')")
    List<User> findAllSsoUsers();

+    /**
+     * Finds SSO users who have never created a session (pending activation) and are not yet
+     * grandfathered.
+     */
+    @Query(
+            "SELECT u FROM User u "
+                    + "LEFT JOIN SessionEntity s ON u.username = s.principalName "
+                    + "WHERE (u.ssoProvider IS NOT NULL "
+                    + "OR LOWER(u.authenticationType) IN ('sso', 'oauth2', 'saml2')) "
+                    + "AND (u.oauthGrandfathered IS NULL OR u.oauthGrandfathered = false) "
+                    + "AND s.sessionId IS NULL")
+    List<User> findPendingSsoUsersWithoutSession();
+
    /**
     * Counts all SSO users - those with sso_provider set OR authenticationType is sso/oauth2/saml2.
     */
@@ -105,22 +105,18 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
            }

            try {
-                log.debug("Validating JWT token");
                jwtService.validateToken(jwtToken);
-                log.debug("JWT token validated successfully");
            } catch (AuthenticationFailureException e) {
-                log.warn("JWT validation failed: {}", e.getMessage());
+                log.debug("JWT validation failed: {}", e.getMessage());
                handleAuthenticationFailure(request, response, e);
                return;
            }

            Map<String, Object> claims = jwtService.extractClaims(jwtToken);
            String tokenUsername = claims.get("sub").toString();
-            log.debug("JWT token username: {}", tokenUsername);

            try {
                authenticate(request, claims);
-                log.debug("Authentication successful for user: {}", tokenUsername);
            } catch (SQLException | UnsupportedProviderException e) {
                log.error("Error processing user authentication for user: {}", tokenUsername, e);
                handleAuthenticationFailure(
@@ -50,7 +50,6 @@ public class JwtService implements JwtServiceInterface {
            KeyPersistenceServiceInterface keyPersistenceService) {
        this.v2Enabled = v2Enabled;
        this.keyPersistenceService = keyPersistenceService;
-        log.info("JwtService initialized");
    }

    @Override
@@ -256,11 +255,9 @@ public class JwtService implements JwtServiceInterface {
        String authHeader = request.getHeader("Authorization");
        if (authHeader != null && authHeader.startsWith("Bearer ")) {
            String token = authHeader.substring(7); // Remove "Bearer " prefix
-            log.debug("JWT token extracted from Authorization header");
            return token;
        }

-        log.debug("No JWT token found in Authorization header");
        return null;
    }

@@ -283,10 +280,9 @@ public class JwtService implements JwtServiceInterface {
                                    .parse(token)
                                    .getHeader()
                                    .get("kid");
-            log.debug("Extracted key ID from token: {}", keyId);
            return keyId;
        } catch (Exception e) {
-            log.warn("Failed to extract key ID from token header: {}", e.getMessage());
+            log.debug("Failed to extract key ID from token header: {}", e.getMessage());
            return null;
        }
    }
@@ -55,7 +55,6 @@ public class KeyPairCleanupService {
            return;
        }

-        log.info("Removing keys older than retention period");
        removeKeys(eligibleKeys);
        keyPersistenceService.refreshActiveKeyPair();
    }
@@ -778,4 +778,30 @@ public class UserService implements UserServiceInterface {

        return updated;
    }
+
+    /**
+     * Grandfathers SSO users who have never created a session (invited/pending accounts). These
+     * users would otherwise be blocked when SSO requires a paid license despite existing before the
+     * policy change.
+     *
+     * @return Number of pending users updated
+     */
+    @Transactional
+    public int grandfatherPendingSsoUsersWithoutSession() {
+        List<User> pendingUsers = userRepository.findPendingSsoUsersWithoutSession();
+        int updated = 0;
+
+        for (User user : pendingUsers) {
+            if (!user.isOauthGrandfathered()) {
+                user.setOauthGrandfathered(true);
+                updated++;
+            }
+        }
+
+        if (updated > 0) {
+            userRepository.saveAll(pendingUsers);
+        }
+
+        return updated;
+    }
 }
@@ -192,10 +192,18 @@ public class UserLicenseSettingsService {
                                + "They will retain OAuth access even without a paid license. "
                                + "New users will require a paid license for OAuth.",
                        updated);
-            } else if (grandfatheredCount > 0) {
-                log.debug(
-                        "OAuth grandfathering already completed: {} users grandfathered",
-                        grandfatheredCount);
+            }
+
+            // Grandfather pending users (invited but never logged in)
+            // The query filters to non-grandfathered users only, so this is idempotent
+            if (grandfatheredCount > 0 || oauthUsersCount > 0) {
+                int pendingUpdated = userService.grandfatherPendingSsoUsersWithoutSession();
+                if (pendingUpdated > 0) {
+                    log.warn(
+                            "OAuth GRANDFATHERING: Marked {} pending SSO users (no prior sessions) as"
+                                    + " grandfathered.",
+                            pendingUpdated);
+                }
            }
        }
    }
@@ -2,6 +2,9 @@ package stirling.software.proprietary.service;

 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.times;
+import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;

 import java.util.Optional;
@@ -198,4 +201,70 @@ class UserLicenseSettingsServiceTest {

        assertEquals(5, result, "Should fall back to default 5 users if grandfathered is 0");
    }
+
+    @Test
+    void grandfatherExistingOAuthUsers_runsOnlyWhenNoneGrandfathered() {
+        // With grandfatheredCount == 0, should run grandfathering for all users
+        when(userService.countOAuthUsers()).thenReturn(10L);
+        when(userService.countGrandfatheredOAuthUsers()).thenReturn(0L);
+        when(userService.grandfatherAllOAuthUsers()).thenReturn(10);
+        when(userService.grandfatherPendingSsoUsersWithoutSession()).thenReturn(0);
+
+        service.grandfatherExistingOAuthUsers();
+
+        verify(userService, times(1)).grandfatherAllOAuthUsers();
+        verify(userService, times(1)).grandfatherPendingSsoUsersWithoutSession();
+    }
+
+    @Test
+    void grandfatherExistingOAuthUsers_skipsMainButRunsPendingWhenSomeAlreadyGrandfathered() {
+        // V2→V2.1 upgrade: some users already grandfathered, but pending users need to be checked
+        when(userService.countOAuthUsers()).thenReturn(10L);
+        when(userService.countGrandfatheredOAuthUsers()).thenReturn(4L);
+        when(userService.grandfatherPendingSsoUsersWithoutSession()).thenReturn(2);
+
+        service.grandfatherExistingOAuthUsers();
+
+        verify(userService, never()).grandfatherAllOAuthUsers();
+        verify(userService, times(1)).grandfatherPendingSsoUsersWithoutSession();
+    }
+
+    @Test
+    void grandfatherExistingOAuthUsers_stillChecksPendingWhenAllUsersGrandfathered() {
+        // All active users grandfathered, but still check for pending users
+        when(userService.countOAuthUsers()).thenReturn(10L);
+        when(userService.countGrandfatheredOAuthUsers()).thenReturn(10L);
+        when(userService.grandfatherPendingSsoUsersWithoutSession()).thenReturn(0);
+
+        service.grandfatherExistingOAuthUsers();
+
+        verify(userService, never()).grandfatherAllOAuthUsers();
+        verify(userService, times(1)).grandfatherPendingSsoUsersWithoutSession();
+    }
+
+    @Test
+    void grandfatherExistingOAuthUsers_skipsWhenNoOAuthUsers() {
+        when(userService.countOAuthUsers()).thenReturn(0L);
+        when(userService.countGrandfatheredOAuthUsers()).thenReturn(0L);
+
+        service.grandfatherExistingOAuthUsers();
+
+        verify(userService, never()).grandfatherAllOAuthUsers();
+        verify(userService, never()).grandfatherPendingSsoUsersWithoutSession();
+    }
+
+    @Test
+    void grandfatherExistingOAuthUsers_grandfathersPendingUsersOnFirstRun() {
+        // Pending users (invited but never logged in) should be grandfathered
+        // during the initial grandfathering run (when grandfatheredCount == 0)
+        when(userService.countOAuthUsers()).thenReturn(5L);
+        when(userService.countGrandfatheredOAuthUsers()).thenReturn(0L);
+        when(userService.grandfatherAllOAuthUsers()).thenReturn(5);
+        when(userService.grandfatherPendingSsoUsersWithoutSession()).thenReturn(3);
+
+        service.grandfatherExistingOAuthUsers();
+
+        verify(userService, times(1)).grandfatherAllOAuthUsers();
+        verify(userService, times(1)).grandfatherPendingSsoUsersWithoutSession();
+    }
 }
@@ -20,6 +20,7 @@
        "@embedpdf/plugin-interaction-manager": "^1.4.1",
        "@embedpdf/plugin-loader": "^1.4.1",
        "@embedpdf/plugin-pan": "^1.4.1",
+        "@embedpdf/plugin-print": "^1.4.1",
        "@embedpdf/plugin-render": "^1.4.1",
        "@embedpdf/plugin-rotate": "^1.4.1",
        "@embedpdf/plugin-scroll": "^1.4.1",
@@ -455,7 +456,6 @@
        }
      ],
      "license": "MIT",
-      "peer": true,
      "engines": {
        "node": ">=18"
      },
@@ -499,7 +499,6 @@
        }
      ],
      "license": "MIT",
-      "peer": true,
      "engines": {
        "node": ">=18"
      }
@@ -580,7 +579,6 @@
      "resolved": "https://registry.npmjs.org/@embedpdf/core/-/core-1.4.1.tgz",
      "integrity": "sha512-TGpxn2CvAKRnOJWJ3bsK+dKBiCp75ehxftRUmv7wAmPomhnG5XrDfoWJungvO+zbbqAwso6PocdeXINVt3hlAw==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@embedpdf/engines": "1.4.1",
        "@embedpdf/models": "1.4.1"
@@ -680,7 +678,6 @@
      "resolved": "https://registry.npmjs.org/@embedpdf/plugin-history/-/plugin-history-1.4.1.tgz",
      "integrity": "sha512-5WLDiNMH6tACkLGGv/lJtNsDeozOhSbrh0mjD1btHun8u7Yscu/Vf8tdJRUOsd+nULivo2nQ2NFNKu0OTbVo8w==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@embedpdf/models": "1.4.1"
      },
@@ -697,7 +694,6 @@
      "resolved": "https://registry.npmjs.org/@embedpdf/plugin-interaction-manager/-/plugin-interaction-manager-1.4.1.tgz",
      "integrity": "sha512-Ng02S9SFIAi9JZS5rI+NXSnZZ1Yk9YYRw4MlN2pig49qOyivZdz0oScZaYxQPewo8ccJkLeghjdeWswOBW/6cA==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@embedpdf/models": "1.4.1"
      },
@@ -715,7 +711,6 @@
      "resolved": "https://registry.npmjs.org/@embedpdf/plugin-loader/-/plugin-loader-1.4.1.tgz",
      "integrity": "sha512-m3ZOk8JygsLxoa4cZ+0BVB5pfRWuBCg2/gPqjhoFZNKTqAFw4J6HGUrhYKg94GRYe+w1cTJl/NbTBYuU5DOrsA==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@embedpdf/models": "1.4.1"
      },
@@ -747,12 +742,28 @@
        "vue": ">=3.2.0"
      }
    },
+    "node_modules/@embedpdf/plugin-print": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/@embedpdf/plugin-print/-/plugin-print-1.4.1.tgz",
+      "integrity": "sha512-YEjU6rQVW8wb125JXl1wma95+JISwADZpfqZZOtvPBRABp6ce4byblDTNjWVmTYWSgKUZrlXCL3Ff3Ig+bjbjw==",
+      "license": "MIT",
+      "dependencies": {
+        "@embedpdf/models": "1.4.1"
+      },
+      "peerDependencies": {
+        "@embedpdf/core": "1.4.1",
+        "preact": "^10.26.4",
+        "react": ">=18.0.0",
+        "react-dom": ">=18.0.0",
+        "svelte": ">=5 <6",
+        "vue": ">=3.2.0"
+      }
+    },
    "node_modules/@embedpdf/plugin-render": {
      "version": "1.4.1",
      "resolved": "https://registry.npmjs.org/@embedpdf/plugin-render/-/plugin-render-1.4.1.tgz",
      "integrity": "sha512-gKCdNKw6WBHBEpTc2DLBWIWOxzsNnaNbpfeY6C4f2Bum0EO+XW3Hl2oIx1uaRHjIhhnXso1J3QweqelsPwDGwg==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@embedpdf/models": "1.4.1"
      },
@@ -787,7 +798,6 @@
      "resolved": "https://registry.npmjs.org/@embedpdf/plugin-scroll/-/plugin-scroll-1.4.1.tgz",
      "integrity": "sha512-Y9O+matB4j4fLim5s/jn7qIi+lMC9vmDJRpJhiWe8bvD9oYLP2xfD/DdhFgAjRKcNhPoxC+j8q8QN5BMeGAv2Q==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@embedpdf/models": "1.4.1"
      },
@@ -824,7 +834,6 @@
      "resolved": "https://registry.npmjs.org/@embedpdf/plugin-selection/-/plugin-selection-1.4.1.tgz",
      "integrity": "sha512-lo5Ytk1PH0PrRKv6zKVupm4t02VGsqIrnSIeP6NO8Ujx0wfqEhj//sqIuO/EwfFVJD8lcQIP9UUo9y8baCrEog==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@embedpdf/models": "1.4.1"
      },
@@ -900,7 +909,6 @@
      "resolved": "https://registry.npmjs.org/@embedpdf/plugin-viewport/-/plugin-viewport-1.4.1.tgz",
      "integrity": "sha512-+TgFHKPCLTBiDYe2DdsmTS37hwQgcZ3dYIc7bE0l5cp+GVwouu1h0MTmjL+90loizeWwCiu10E/zXR6hz+CUaQ==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@embedpdf/models": "1.4.1"
      },
@@ -1056,7 +1064,6 @@
      "resolved": "https://registry.npmjs.org/@emotion/react/-/react-11.14.0.tgz",
      "integrity": "sha512-O000MLDBDdk/EohJPFUqvnp4qnHeYkVP5B0xEG0D/L7cOKP9kefu2DXn8dj74cQfsEzUqh+sr1RzFqiL1o+PpA==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@babel/runtime": "^7.18.3",
        "@emotion/babel-plugin": "^11.13.5",
@@ -1100,7 +1107,6 @@
      "resolved": "https://registry.npmjs.org/@emotion/styled/-/styled-11.14.1.tgz",
      "integrity": "sha512-qEEJt42DuToa3gurlH4Qqc1kVpNq8wO8cJtDzU46TjlzWjDlsVyevtYCRijVq3SrHsROS+gVQ8Fnea108GnKzw==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@babel/runtime": "^7.18.3",
        "@emotion/babel-plugin": "^11.13.5",
@@ -2131,7 +2137,6 @@
      "resolved": "https://registry.npmjs.org/@mantine/core/-/core-8.3.6.tgz",
      "integrity": "sha512-paTl+0x+O/QtgMtqVJaG8maD8sfiOdgPmLOyG485FmeGZ1L3KMdEkhxZtmdGlDFsLXhmMGQ57ducT90bvhXX5A==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@floating-ui/react": "^0.27.16",
        "clsx": "^2.1.1",
@@ -2182,7 +2187,6 @@
      "resolved": "https://registry.npmjs.org/@mantine/hooks/-/hooks-8.3.6.tgz",
      "integrity": "sha512-liHfaWXHAkLjJy+Bkr29UsCwAoDQ/a64WrM67lksx8F0qqyjR5RQH8zVlhuOjdpQnwtlUkE/YiTvbJiPcoI0bw==",
      "license": "MIT",
-      "peer": true,
      "peerDependencies": {
        "react": "^18.x || ^19.x"
      }
@@ -2250,7 +2254,6 @@
      "resolved": "https://registry.npmjs.org/@mui/material/-/material-7.3.5.tgz",
      "integrity": "sha512-8VVxFmp1GIm9PpmnQoCoYo0UWHoOrdA57tDL62vkpzEgvb/d71Wsbv4FRg7r1Gyx7PuSo0tflH34cdl/NvfHNQ==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@babel/runtime": "^7.28.4",
        "@mui/core-downloads-tracker": "^7.3.5",
@@ -3183,7 +3186,6 @@
      "resolved": "https://registry.npmjs.org/@stripe/stripe-js/-/stripe-js-7.9.0.tgz",
      "integrity": "sha512-ggs5k+/0FUJcIgNY08aZTqpBTtbExkJMYMLSMwyucrhtWexVOEY1KJmhBsxf+E/Q15f5rbwBpj+t0t2AW2oCsQ==",
      "license": "MIT",
-      "peer": true,
      "engines": {
        "node": ">=12.16"
      }
@@ -3302,6 +3304,7 @@
      "resolved": "https://registry.npmjs.org/@sveltejs/acorn-typescript/-/acorn-typescript-1.0.6.tgz",
      "integrity": "sha512-4awhxtMh4cx9blePWl10HRHj8Iivtqj+2QdDCSMDzxG+XKa9+VCNupQuCuvzEhYPzZSrX+0gC+0lHA/0fFKKQQ==",
      "license": "MIT",
+      "peer": true,
      "peerDependencies": {
        "acorn": "^8.9.0"
      }
@@ -4078,7 +4081,6 @@
      "integrity": "sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@babel/code-frame": "^7.10.4",
        "@babel/runtime": "^7.12.5",
@@ -4407,7 +4409,6 @@
      "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.2.tgz",
      "integrity": "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "csstype": "^3.0.2"
      }
@@ -4418,7 +4419,6 @@
      "integrity": "sha512-9KQPoO6mZCi7jcIStSnlOWn2nEF3mNmyr3rIAsGnAbQKYbRLyqmeSc39EVgtxXVia+LMT8j3knZLAZAh+xLmrw==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "peerDependencies": {
        "@types/react": "^19.2.0"
      }
@@ -4488,7 +4488,6 @@
      "integrity": "sha512-6m1I5RmHBGTnUGS113G04DMu3CpSdxCAU/UvtjNWL4Nuf3MW9tQhiJqRlHzChIkhy6kZSAQmc+I1bcGjE3yNKg==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@typescript-eslint/scope-manager": "8.46.3",
        "@typescript-eslint/types": "8.46.3",
@@ -5202,6 +5201,7 @@
      "resolved": "https://registry.npmjs.org/@vue/reactivity/-/reactivity-3.5.24.tgz",
      "integrity": "sha512-BM8kBhtlkkbnyl4q+HiF5R5BL0ycDPfihowulm02q3WYp2vxgPcJuZO866qa/0u3idbMntKEtVNuAUp5bw4teg==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@vue/shared": "3.5.24"
      }
@@ -5211,6 +5211,7 @@
      "resolved": "https://registry.npmjs.org/@vue/runtime-core/-/runtime-core-3.5.24.tgz",
      "integrity": "sha512-RYP/byyKDgNIqfX/gNb2PB55dJmM97jc9wyF3jK7QUInYKypK2exmZMNwnjueWwGceEkP6NChd3D2ZVEp9undQ==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@vue/reactivity": "3.5.24",
        "@vue/shared": "3.5.24"
@@ -5221,6 +5222,7 @@
      "resolved": "https://registry.npmjs.org/@vue/runtime-dom/-/runtime-dom-3.5.24.tgz",
      "integrity": "sha512-Z8ANhr/i0XIluonHVjbUkjvn+CyrxbXRIxR7wn7+X7xlcb7dJsfITZbkVOeJZdP8VZwfrWRsWdShH6pngMxRjw==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@vue/reactivity": "3.5.24",
        "@vue/runtime-core": "3.5.24",
@@ -5233,6 +5235,7 @@
      "resolved": "https://registry.npmjs.org/@vue/server-renderer/-/server-renderer-3.5.24.tgz",
      "integrity": "sha512-Yh2j2Y4G/0/4z/xJ1Bad4mxaAk++C2v4kaa8oSYTMJBJ00/ndPuxCnWeot0/7/qafQFLh5pr6xeV6SdMcE/G1w==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@vue/compiler-ssr": "3.5.24",
        "@vue/shared": "3.5.24"
@@ -5259,7 +5262,6 @@
      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
      "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
      "license": "MIT",
-      "peer": true,
      "bin": {
        "acorn": "bin/acorn"
      },
@@ -5667,6 +5669,7 @@
      "resolved": "https://registry.npmjs.org/axobject-query/-/axobject-query-4.1.0.tgz",
      "integrity": "sha512-qIj0G9wZbMGNLjLmg1PT6v2mE9AH2zlnADJD/2tC6E00hgmhUOfEB6greHPAfLRSufHqROIUTkw6E+M3lH0PTQ==",
      "license": "Apache-2.0",
+      "peer": true,
      "engines": {
        "node": ">= 0.4"
      }
@@ -5943,7 +5946,6 @@
        }
      ],
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "baseline-browser-mapping": "^2.8.19",
        "caniuse-lite": "^1.0.30001751",
@@ -6991,8 +6993,7 @@
      "resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1521046.tgz",
      "integrity": "sha512-vhE6eymDQSKWUXwwA37NtTTVEzjtGVfDr3pRbsWEQ5onH/Snp2c+2xZHWJJawG/0hCCJLRGt4xVtEVUVILol4w==",
      "dev": true,
-      "license": "BSD-3-Clause",
-      "peer": true
+      "license": "BSD-3-Clause"
    },
    "node_modules/dezalgo": {
      "version": "1.0.4",
@@ -7387,7 +7388,6 @@
      "integrity": "sha512-BhHmn2yNOFA9H9JmmIVKJmd288g9hrVRDkdoIgRCRuSySRUHH7r/DI6aAXW9T1WwUuY3DFgrcaqB+deURBLR5g==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@eslint-community/eslint-utils": "^4.8.0",
        "@eslint-community/regexpp": "^4.12.1",
@@ -7558,7 +7558,6 @@
      "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@rtsao/scc": "^1.1.0",
        "array-includes": "^3.1.9",
@@ -7725,7 +7724,8 @@
      "version": "1.2.2",
      "resolved": "https://registry.npmjs.org/esm-env/-/esm-env-1.2.2.tgz",
      "integrity": "sha512-Epxrv+Nr/CaL4ZcFGPJIYLWFom+YeV1DqMLHJoEd9SYRxNbaFruBwfEX/kkHUJf55j2+TUbmDcmuilbP1TmXHA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
    },
    "node_modules/espree": {
      "version": "10.4.0",
@@ -7790,6 +7790,7 @@
      "resolved": "https://registry.npmjs.org/esrap/-/esrap-2.1.2.tgz",
      "integrity": "sha512-DgvlIQeowRNyvLPWW4PT7Gu13WznY288Du086E751mwwbsgr29ytBiYeLzAGIo0qk3Ujob0SDk8TiSaM5WQzNg==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@jridgewell/sourcemap-codec": "^1.4.15"
      }
@@ -8880,7 +8881,6 @@
        }
      ],
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@babel/runtime": "^7.27.6"
      },
@@ -9357,6 +9357,7 @@
      "resolved": "https://registry.npmjs.org/is-reference/-/is-reference-3.0.3.tgz",
      "integrity": "sha512-ixkJoqQvAP88E6wLydLGGqCJsrFUnqoH6HnaczB8XmDH1oaWU+xxdptvikTgaEhtZ53Ky6YXiBuUI2WXLMCwjw==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "@types/estree": "^1.0.6"
      }
@@ -9677,7 +9678,6 @@
      "integrity": "sha512-Pcfm3eZ+eO4JdZCXthW9tCDT3nF4K+9dmeZ+5X39n+Kqz0DDIABRP5CAEOHRFZk8RGuC2efksTJxrjp8EXCunQ==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@acemir/cssom": "^0.9.19",
        "@asamuzakjp/dom-selector": "^6.7.3",
@@ -10264,7 +10264,8 @@
      "version": "3.0.0",
      "resolved": "https://registry.npmjs.org/locate-character/-/locate-character-3.0.0.tgz",
      "integrity": "sha512-SW13ws7BjaeJ6p7Q6CO2nchbYEc3X3J6WrmTTDto7yMPqVSZTUyY5Tjbid+Ab8gLnATtygYtiDIJGQRRn2ZOiA==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
    },
    "node_modules/locate-path": {
      "version": "6.0.0",
@@ -11410,7 +11411,6 @@
        }
      ],
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "nanoid": "^3.3.11",
        "picocolors": "^1.1.1",
@@ -11690,7 +11690,6 @@
      "resolved": "https://registry.npmjs.org/preact/-/preact-10.27.2.tgz",
      "integrity": "sha512-5SYSgFKSyhCbk6SrXyMpqjb5+MQBgfvEKE/OC+PujcY34sOpqtr+0AZQtPYx5IA6VxynQ7rUPCtKzyovpj9Bpg==",
      "license": "MIT",
-      "peer": true,
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/preact"
@@ -12073,7 +12072,6 @@
      "resolved": "https://registry.npmjs.org/react/-/react-19.2.0.tgz",
      "integrity": "sha512-tmbWg6W31tQLeB5cdIBOicJDJRR2KzXsV7uSK9iNfLWQ5bIZfxuPEHp7M8wiHyHnn0DD1i7w3Zmin0FtkrwoCQ==",
      "license": "MIT",
-      "peer": true,
      "engines": {
        "node": ">=0.10.0"
      }
@@ -12083,7 +12081,6 @@
      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.0.tgz",
      "integrity": "sha512-UlbRu4cAiGaIewkPyiRGJk0imDN2T3JjieT6spoL2UeSf5od4n5LB/mQ4ejmxhCFT1tYe8IvaFulzynWovsEFQ==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "scheduler": "^0.27.0"
      },
@@ -13595,6 +13592,7 @@
      "resolved": "https://registry.npmjs.org/aria-query/-/aria-query-5.3.2.tgz",
      "integrity": "sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw==",
      "license": "Apache-2.0",
+      "peer": true,
      "engines": {
        "node": ">= 0.4"
      }
@@ -13803,7 +13801,6 @@
      "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "engines": {
        "node": ">=12"
      },
@@ -14105,7 +14102,6 @@
      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
      "devOptional": true,
      "license": "Apache-2.0",
-      "peer": true,
      "bin": {
        "tsc": "bin/tsc",
        "tsserver": "bin/tsserver"
@@ -14187,7 +14183,6 @@
      "dev": true,
      "hasInstallScript": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "napi-postinstall": "^0.3.0"
      },
@@ -14392,7 +14387,6 @@
      "integrity": "sha512-BxAKBWmIbrDgrokdGZH1IgkIk/5mMHDreLDmCJ0qpyJaAteP8NvMhkwr/ZCQNqNH97bw/dANTE9PDzqwJghfMQ==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "esbuild": "^0.25.0",
        "fdir": "^6.5.0",
@@ -14544,7 +14538,6 @@
      "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "engines": {
        "node": ">=12"
      },
@@ -14558,7 +14551,6 @@
      "integrity": "sha512-LUCP5ev3GURDysTWiP47wRRUpLKMOfPh+yKTx3kVIEiu5KOMeqzpnYNsKyOoVrULivR8tLcks4+lga33Whn90A==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@types/chai": "^5.2.2",
        "@vitest/expect": "3.2.4",
@@ -15170,7 +15162,8 @@
      "version": "1.1.4",
      "resolved": "https://registry.npmjs.org/zimmerframe/-/zimmerframe-1.1.4.tgz",
      "integrity": "sha512-B58NGBEoc8Y9MWWCQGl/gq9xBCe4IiKM0a2x7GZdQKOW5Exr8S1W24J6OgM1njK8xCRGvAJIL/MxXHf6SkmQKQ==",
-      "license": "MIT"
+      "license": "MIT",
+      "peer": true
    },
    "node_modules/zod": {
      "version": "3.25.76",
@@ -16,6 +16,7 @@
    "@embedpdf/plugin-interaction-manager": "^1.4.1",
    "@embedpdf/plugin-loader": "^1.4.1",
    "@embedpdf/plugin-pan": "^1.4.1",
+    "@embedpdf/plugin-print": "^1.4.1",
    "@embedpdf/plugin-render": "^1.4.1",
    "@embedpdf/plugin-rotate": "^1.4.1",
    "@embedpdf/plugin-scroll": "^1.4.1",
@@ -3899,6 +3899,7 @@ toggleSidebar = "Toggle Sidebar"
 exportSelected = "Export Selected Pages"
 toggleAnnotations = "Toggle Annotations Visibility"
 annotationMode = "Toggle Annotation Mode"
+print = "Print PDF"
 draw = "Draw"
 save = "Save"
 saveChanges = "Save Changes"
@@ -3,7 +3,7 @@ import { AppProviders } from "@app/components/AppProviders";
 import { AppLayout } from "@app/components/AppLayout";
 import { LoadingFallback } from "@app/components/shared/LoadingFallback";
 import HomePage from "@app/pages/HomePage";
-import OnboardingTour from "@app/components/onboarding/OnboardingTour";
+import Onboarding from "@app/components/onboarding/Onboarding";

 // Import global styles
 import "@app/styles/tailwind.css";
@@ -19,7 +19,7 @@ export default function App() {
      <AppProviders>
        <AppLayout>
          <HomePage />
-          <OnboardingTour />
+          <Onboarding />
        </AppLayout>
      </AppProviders>
    </Suspense>
@@ -12,7 +12,6 @@ import { AppConfigProvider, AppConfigProviderProps, AppConfigRetryOptions } from
 import { RightRailProvider } from "@app/contexts/RightRailContext";
 import { ViewerProvider } from "@app/contexts/ViewerContext";
 import { SignatureProvider } from "@app/contexts/SignatureContext";
-import { OnboardingProvider } from "@app/contexts/OnboardingContext";
 import { TourOrchestrationProvider } from "@app/contexts/TourOrchestrationContext";
 import { AdminTourOrchestrationProvider } from "@app/contexts/AdminTourOrchestrationContext";
 import { PageEditorProvider } from "@app/contexts/PageEditorContext";
@@ -77,7 +76,6 @@ export function AppProviders({ children, appConfigRetryOptions, appConfigProvide
      <RainbowThemeProvider>
        <ErrorBoundary>
          <BannerProvider>
-            <OnboardingProvider>
              <AppConfigProvider
                retryOptions={appConfigRetryOptions}
                {...appConfigProviderProps}
@@ -113,7 +111,6 @@ export function AppProviders({ children, appConfigRetryOptions, appConfigProvide
                    </ToolRegistryProvider>
                  </FileContextProvider>
              </AppConfigProvider>
-            </OnboardingProvider>
          </BannerProvider>
        </ErrorBoundary>
      </RainbowThemeProvider>
@@ -1,33 +0,0 @@
-import { FLOW_SEQUENCES, type SlideId } from '@app/components/onboarding/onboardingFlowConfig';
-
-export type FlowType = 'login-admin' | 'login-user' | 'no-login' | 'no-login-admin';
-
-export interface FlowConfig {
-  type: FlowType;
-  ids: SlideId[];
-}
-
-export function resolveFlow(enableLogin: boolean, isAdmin: boolean, selfReportedAdmin: boolean): FlowConfig {
-  if (!enableLogin) {
-    return selfReportedAdmin
-      ? {
-          type: 'no-login-admin',
-          ids: [...FLOW_SEQUENCES.noLoginBase, ...FLOW_SEQUENCES.noLoginAdmin],
-        }
-      : {
-          type: 'no-login',
-          ids: FLOW_SEQUENCES.noLoginBase,
-        };
-  }
-
-  return isAdmin
-    ? {
-        type: 'login-admin',
-        ids: FLOW_SEQUENCES.loginAdmin,
-      }
-    : {
-        type: 'login-user',
-        ids: FLOW_SEQUENCES.loginUser,
-      };
-}
-
@@ -6,7 +6,7 @@ import { ButtonDefinition, type FlowState } from '@app/components/onboarding/onb
 import type { LicenseNotice } from '@app/types/types';
 import type { ButtonAction } from '@app/components/onboarding/onboardingFlowConfig';

-interface RenderButtonsProps {
+interface SlideButtonsProps {
  slideDefinition: {
    buttons: ButtonDefinition[];
    id: string;
@@ -16,7 +16,7 @@ interface RenderButtonsProps {
  onAction: (action: ButtonAction) => void;
 }

-export function renderButtons({ slideDefinition, licenseNotice, flowState, onAction }: RenderButtonsProps) {
+export function SlideButtons({ slideDefinition, licenseNotice, flowState, onAction }: SlideButtonsProps) {
  const { t } = useTranslation();
  const leftButtons = slideDefinition.buttons.filter((btn) => btn.group === 'left');
  const rightButtons = slideDefinition.buttons.filter((btn) => btn.group === 'right');
@@ -105,5 +105,4 @@ export function renderButtons({ slideDefinition, licenseNotice, flowState, onAct
      <Group gap={12}>{rightButtons.map(renderButton)}</Group>
    </Group>
  );
-}
-
+}
@@ -1,21 +0,0 @@
-import type { LicenseNotice } from '@app/types/types';
-
-export interface InitialOnboardingModalProps {
-  opened: boolean;
-  onClose: () => void;
-  onRequestServerLicense?: (options?: { deferUntilTourComplete?: boolean; selfReportedAdmin?: boolean }) => void;
-  onLicenseNoticeUpdate?: (licenseNotice: LicenseNotice) => void;
-}
-
-export interface OnboardingState {
-  step: number;
-  selectedRole: 'admin' | 'user' | null;
-  selfReportedAdmin: boolean;
-}
-
-export const DEFAULT_STATE: OnboardingState = {
-  step: 0,
-  selectedRole: null,
-  selfReportedAdmin: false,
-};
-
@@ -1,381 +0,0 @@
-import { useCallback, useEffect, useMemo, useState, useRef } from 'react';
-import { usePreferences } from '@app/contexts/PreferencesContext';
-import { useOnboarding } from '@app/contexts/OnboardingContext';
-import { useOs } from '@app/hooks/useOs';
-import { useNavigate } from 'react-router-dom';
-import {
-  SLIDE_DEFINITIONS,
-  type ButtonAction,
-  type FlowState,
-  type SlideId,
-} from '@app/components/onboarding/onboardingFlowConfig';
-import type { LicenseNotice } from '@app/types/types';
-import { resolveFlow } from '@app/components/onboarding/InitialOnboardingModal/flowResolver';
-import { useServerExperience } from '@app/hooks/useServerExperience';
-import { DEFAULT_STATE, type InitialOnboardingModalProps, type OnboardingState } from '@app/components/onboarding/InitialOnboardingModal/types';
-import { DOWNLOAD_URLS } from '@app/constants/downloads';
-
-interface UseInitialOnboardingStateResult {
-  state: OnboardingState;
-  totalSteps: number;
-  slideDefinition: (typeof SLIDE_DEFINITIONS)[SlideId];
-  currentSlide: ReturnType<(typeof SLIDE_DEFINITIONS)[SlideId]['createSlide']>;
-  licenseNotice: LicenseNotice;
-  flowState: FlowState;
-  closeAndMarkSeen: () => void;
-  handleButtonAction: (action: ButtonAction) => void;
-}
-
-export function useInitialOnboardingState({
-  opened,
-  onClose,
-  onRequestServerLicense,
-  onLicenseNoticeUpdate,
-}: InitialOnboardingModalProps): UseInitialOnboardingStateResult | null {
-  const { preferences, updatePreference } = usePreferences();
-  const { startTour } = useOnboarding();
-  const {
-    loginEnabled: loginEnabledFromServer,
-    configIsAdmin,
-    totalUsers: serverTotalUsers,
-    userCountResolved: serverUserCountResolved,
-    freeTierLimit,
-    hasPaidLicense,
-    scenarioKey,
-    setSelfReportedAdmin,
-    isNewServer,
-  } = useServerExperience();
-  const osType = useOs();
-  const navigate = useNavigate();
-  const selectedDownloadUrlRef = useRef<string>('');
-
-  const [state, setState] = useState<OnboardingState>(DEFAULT_STATE);
-
-  const resetState = useCallback(() => {
-    setState(DEFAULT_STATE);
-  }, []);
-
-  useEffect(() => {
-    if (!opened) {
-      resetState();
-    }
-  }, [opened, resetState]);
-
-  const handleRoleSelect = useCallback(
-    (role: 'admin' | 'user' | null) => {
-      const isAdminSelection = role === 'admin';
-      setState((prev) => ({
-        ...prev,
-        selectedRole: role,
-        selfReportedAdmin: isAdminSelection,
-      }));
-
-      if (typeof window !== 'undefined') {
-        if (isAdminSelection) {
-          window.localStorage.setItem('stirling-self-reported-admin', 'true');
-        } else {
-          window.localStorage.removeItem('stirling-self-reported-admin');
-        }
-      }
-
-      setSelfReportedAdmin(isAdminSelection);
-    },
-    [setSelfReportedAdmin],
-  );
-
-  const closeAndMarkSeen = useCallback(() => {
-    if (!preferences.hasSeenIntroOnboarding) {
-      updatePreference('hasSeenIntroOnboarding', true);
-    }
-    onClose();
-  }, [onClose, preferences.hasSeenIntroOnboarding, updatePreference]);
-
-  const isAdmin = configIsAdmin;
-  const enableLogin = loginEnabledFromServer;
-
-  const effectiveEnableLogin = enableLogin;
-  const effectiveIsAdmin = isAdmin;
-  const shouldAssumeAdminForNewServer = Boolean(isNewServer) && !effectiveEnableLogin;
-
-  useEffect(() => {
-    if (shouldAssumeAdminForNewServer && !state.selfReportedAdmin) {
-      handleRoleSelect('admin');
-    }
-  }, [handleRoleSelect, shouldAssumeAdminForNewServer, state.selfReportedAdmin]);
-
-  const shouldUseServerCount =
-    (effectiveEnableLogin && effectiveIsAdmin) || !effectiveEnableLogin;
-  const licenseUserCountFromServer =
-    shouldUseServerCount && serverUserCountResolved ? serverTotalUsers : null;
-
-  const effectiveLicenseUserCount = licenseUserCountFromServer ?? null;
-
-  const os = useMemo(() => {
-    switch (osType) {
-      case 'windows':
-        return { label: 'Windows', url: DOWNLOAD_URLS.WINDOWS };
-      case 'mac-apple':
-        return { label: 'Mac (Apple Silicon)', url: DOWNLOAD_URLS.MAC_APPLE_SILICON };
-      case 'mac-intel':
-        return { label: 'Mac (Intel)', url: DOWNLOAD_URLS.MAC_INTEL };
-      case 'linux-x64':
-      case 'linux-arm64':
-        return { label: 'Linux', url: DOWNLOAD_URLS.LINUX_DOCS };
-      default:
-        return { label: '', url: '' };
-    }
-  }, [osType]);
-
-  const osOptions = useMemo(() => {
-    const options = [
-      { label: 'Windows', url: DOWNLOAD_URLS.WINDOWS, value: 'windows' },
-      { label: 'Mac (Apple Silicon)', url: DOWNLOAD_URLS.MAC_APPLE_SILICON, value: 'mac-apple' },
-      { label: 'Mac (Intel)', url: DOWNLOAD_URLS.MAC_INTEL, value: 'mac-intel' },
-      { label: 'Linux', url: DOWNLOAD_URLS.LINUX_DOCS, value: 'linux' },
-    ];
-    return options.filter(opt => opt.url);
-  }, []);
-
-  const resolvedFlow = useMemo(
-    () => resolveFlow(effectiveEnableLogin, effectiveIsAdmin, state.selfReportedAdmin),
-    [effectiveEnableLogin, effectiveIsAdmin, state.selfReportedAdmin],
-  );
-  const shouldSkipSecurityCheck = shouldAssumeAdminForNewServer;
-  const flowSlideIds = useMemo(
-    () =>
-      shouldSkipSecurityCheck
-        ? resolvedFlow.ids.filter((id) => id !== 'security-check')
-        : resolvedFlow.ids,
-    [resolvedFlow.ids, shouldSkipSecurityCheck],
-  );
-  const flowType = resolvedFlow.type;
-  const totalSteps = flowSlideIds.length;
-  const maxIndex = Math.max(totalSteps - 1, 0);
-
-  useEffect(() => {
-    if (state.step >= flowSlideIds.length) {
-      setState((prev) => ({
-        ...prev,
-        step: Math.max(flowSlideIds.length - 1, 0),
-      }));
-    }
-  }, [flowSlideIds.length, state.step]);
-
-  const currentSlideId = flowSlideIds[state.step] ?? flowSlideIds[flowSlideIds.length - 1];
-  const slideDefinition = SLIDE_DEFINITIONS[currentSlideId];
-
-  if (!slideDefinition) {
-    return null;
-  }
-
-  const scenarioProvidesInfo =
-    scenarioKey && scenarioKey !== 'unknown' && scenarioKey !== 'licensed';
-  const scenarioIndicatesAdmin = scenarioProvidesInfo
-    ? scenarioKey!.includes('admin')
-    : state.selfReportedAdmin || effectiveIsAdmin;
-  const scenarioIndicatesOverLimit = scenarioProvidesInfo
-    ? scenarioKey!.includes('over-limit')
-    : effectiveLicenseUserCount != null && effectiveLicenseUserCount > freeTierLimit;
-  const scenarioRequiresLicense =
-    scenarioKey === 'licensed' ? false : scenarioKey === 'unknown' ? !hasPaidLicense : true;
-
-  const shouldShowServerLicenseInfo = scenarioIndicatesAdmin && scenarioRequiresLicense;
-
-  const licenseNotice = useMemo<LicenseNotice>(
-    () => ({
-      totalUsers: effectiveLicenseUserCount,
-      freeTierLimit,
-      isOverLimit: scenarioIndicatesOverLimit,
-      requiresLicense: shouldShowServerLicenseInfo,
-    }),
-    [
-      effectiveLicenseUserCount,
-      freeTierLimit,
-      scenarioIndicatesOverLimit,
-      shouldShowServerLicenseInfo,
-    ],
-  );
-
-  const requestServerLicenseIfNeeded = useCallback(
-    (options?: { deferUntilTourComplete?: boolean; selfReportedAdmin?: boolean }) => {
-      if (!shouldShowServerLicenseInfo) {
-        return;
-      }
-      onRequestServerLicense?.(options);
-    },
-    [onRequestServerLicense, shouldShowServerLicenseInfo],
-  );
-
-  useEffect(() => {
-    onLicenseNoticeUpdate?.(licenseNotice);
-  }, [licenseNotice, onLicenseNoticeUpdate]);
-
-  // Initialize ref with default URL
-  useEffect(() => {
-    if (!selectedDownloadUrlRef.current && os.url) {
-      selectedDownloadUrlRef.current = os.url;
-    }
-  }, [os.url]);
-
-  const handleDownloadUrlChange = useCallback((url: string) => {
-    selectedDownloadUrlRef.current = url;
-  }, []);
-
-  const currentSlide = slideDefinition.createSlide({
-    osLabel: os.label,
-    osUrl: os.url,
-    osOptions,
-    onDownloadUrlChange: handleDownloadUrlChange,
-    selectedRole: state.selectedRole,
-    onRoleSelect: handleRoleSelect,
-    licenseNotice,
-    loginEnabled: effectiveEnableLogin,
-  });
-
-  const goNext = useCallback(() => {
-    setState((prev) => ({
-      ...prev,
-      step: Math.min(prev.step + 1, maxIndex),
-    }));
-  }, [maxIndex]);
-
-  const goPrev = useCallback(() => {
-    setState((prev) => ({
-      ...prev,
-      step: Math.max(prev.step - 1, 0),
-    }));
-  }, []);
-
-  const launchTour = useCallback(
-    (mode: 'admin' | 'tools', options?: { closeOnboardingSlides?: boolean }) => {
-      if (options?.closeOnboardingSlides) {
-        closeAndMarkSeen();
-      }
-
-      startTour(mode, {
-        source: 'initial-onboarding-modal',
-        metadata: {
-          hasCompletedOnboarding: preferences.hasCompletedOnboarding,
-          toolPanelModePromptSeen: preferences.toolPanelModePromptSeen,
-          selfReportedAdmin: state.selfReportedAdmin,
-        },
-      });
-    },
-    [closeAndMarkSeen, preferences.hasCompletedOnboarding, preferences.toolPanelModePromptSeen, startTour, state.selfReportedAdmin],
-  );
-
-  const handleButtonAction = useCallback(
-    (action: ButtonAction) => {
-      const currentSlideIdLocal = currentSlideId;
-      const shouldAutoLaunchLoginUserTour =
-        flowType === 'login-user' && currentSlideIdLocal === 'desktop-install';
-
-      switch (action) {
-        case 'next':
-          if (shouldAutoLaunchLoginUserTour) {
-            launchTour('tools', { closeOnboardingSlides: true });
-            return;
-          }
-          goNext();
-          return;
-        case 'prev':
-          goPrev();
-          return;
-        case 'close':
-          closeAndMarkSeen();
-          return;
-        case 'download-selected': {
-          const downloadUrl = selectedDownloadUrlRef.current || os.url || currentSlide.downloadUrl;
-          if (downloadUrl) {
-            window.open(downloadUrl, '_blank', 'noopener');
-          }
-          if (shouldAutoLaunchLoginUserTour) {
-            launchTour('tools', { closeOnboardingSlides: true });
-            return;
-          }
-          goNext();
-          return;
-        }
-        case 'complete-close':
-          updatePreference('hasCompletedOnboarding', true);
-          closeAndMarkSeen();
-          return;
-        case 'security-next':
-          if (!state.selectedRole) {
-            return;
-          }
-          if (state.selectedRole === 'admin') {
-            goNext();
-          } else {
-            launchTour('tools', { closeOnboardingSlides: true });
-          }
-          return;
-        case 'launch-admin':
-          requestServerLicenseIfNeeded({
-            deferUntilTourComplete: true,
-            selfReportedAdmin: state.selfReportedAdmin || effectiveIsAdmin,
-          });
-          launchTour('admin', { closeOnboardingSlides: true });
-          return;
-        case 'launch-tools':
-          launchTour('tools', { closeOnboardingSlides: true });
-          return;
-        case 'launch-auto': {
-          const launchMode = state.selfReportedAdmin || effectiveIsAdmin ? 'admin' : 'tools';
-          if (launchMode === 'admin') {
-            requestServerLicenseIfNeeded({
-              deferUntilTourComplete: true,
-              selfReportedAdmin: state.selfReportedAdmin || effectiveIsAdmin,
-            });
-          }
-          launchTour(launchMode, { closeOnboardingSlides: true });
-          return;
-        }
-        case 'skip-to-license':
-          updatePreference('hasCompletedOnboarding', true);
-          requestServerLicenseIfNeeded({
-            deferUntilTourComplete: false,
-            selfReportedAdmin: state.selfReportedAdmin || effectiveIsAdmin,
-          });
-          closeAndMarkSeen();
-          return;
-        case 'see-plans':
-          closeAndMarkSeen();
-          navigate('/settings/adminPlan');
-          return;
-        default:
-          return;
-      }
-    },
-    [
-      closeAndMarkSeen,
-      currentSlide,
-      effectiveIsAdmin,
-      flowType,
-      goNext,
-      goPrev,
-      launchTour,
-      navigate,
-      requestServerLicenseIfNeeded,
-      onRequestServerLicense,
-      os.url,
-      state.selectedRole,
-      state.selfReportedAdmin,
-      updatePreference,
-    ],
-  );
-
-  const flowState: FlowState = { selectedRole: state.selectedRole };
-
-  return {
-    state,
-    totalSteps,
-    slideDefinition,
-    currentSlide,
-    licenseNotice,
-    flowState,
-    closeAndMarkSeen,
-    handleButtonAction,
-  };
-}
-
@@ -0,0 +1,319 @@
+import { useEffect, useMemo, useCallback, useState } from 'react';
+import { type StepType } from '@reactour/tour';
+import { useTranslation } from 'react-i18next';
+import { useNavigate, useLocation } from 'react-router-dom';
+import { isAuthRoute } from '@app/constants/routes';
+import { dispatchTourState } from '@app/constants/events';
+import { useOnboardingOrchestrator } from '@app/components/onboarding/orchestrator/useOnboardingOrchestrator';
+import { markStepSeen } from '@app/components/onboarding/orchestrator/onboardingStorage';
+import OnboardingTour, { type AdvanceArgs, type CloseArgs } from '@app/components/onboarding/OnboardingTour';
+import OnboardingModalSlide from '@app/components/onboarding/OnboardingModalSlide';
+import {
+  useServerLicenseRequest,
+  useTourRequest,
+} from '@app/components/onboarding/useOnboardingEffects';
+import { useOnboardingDownload } from '@app/components/onboarding/useOnboardingDownload';
+import { SLIDE_DEFINITIONS, type SlideId, type ButtonAction } from '@app/components/onboarding/onboardingFlowConfig';
+import ToolPanelModePrompt from '@app/components/tools/ToolPanelModePrompt';
+import { useTourOrchestration } from '@app/contexts/TourOrchestrationContext';
+import { useAdminTourOrchestration } from '@app/contexts/AdminTourOrchestrationContext';
+import { createUserStepsConfig } from '@app/components/onboarding/userStepsConfig';
+import { createAdminStepsConfig } from '@app/components/onboarding/adminStepsConfig';
+import { removeAllGlows } from '@app/components/onboarding/tourGlow';
+import { useFilesModalContext } from '@app/contexts/FilesModalContext';
+import { useServerExperience } from '@app/hooks/useServerExperience';
+import AdminAnalyticsChoiceModal from '@app/components/shared/AdminAnalyticsChoiceModal';
+import '@app/components/onboarding/OnboardingTour.css';
+
+export default function Onboarding() {
+  const { t } = useTranslation();
+  const navigate = useNavigate();
+  const location = useLocation();
+  const { state, actions } = useOnboardingOrchestrator();
+  const serverExperience = useServerExperience();
+  const onAuthRoute = isAuthRoute(location.pathname);
+  const { currentStep, isActive, isLoading, runtimeState, activeFlow } = state;
+
+  const { osInfo, osOptions, setSelectedDownloadUrl, handleDownloadSelected } = useOnboardingDownload();
+  const { showLicenseSlide, licenseNotice: externalLicenseNotice, closeLicenseSlide } = useServerLicenseRequest();
+  const { tourRequested: externalTourRequested, requestedTourType, clearTourRequest } = useTourRequest();
+
+  const handleRoleSelect = useCallback((role: 'admin' | 'user' | null) => {
+    actions.updateRuntimeState({ selectedRole: role });
+    serverExperience.setSelfReportedAdmin(role === 'admin');
+  }, [actions, serverExperience]);
+
+  const handlePasswordChanged = useCallback(() => {
+    actions.updateRuntimeState({ requiresPasswordChange: false });
+    window.location.href = '/login';
+  }, [actions]);
+
+  const handleButtonAction = useCallback((action: ButtonAction) => {
+    switch (action) {
+      case 'next':
+      case 'complete-close':
+        actions.complete();
+        break;
+      case 'prev':
+        actions.prev();
+        break;
+      case 'close':
+        actions.skip();
+        break;
+      case 'download-selected':
+        handleDownloadSelected();
+        actions.complete();
+        break;
+      case 'security-next':
+        if (!runtimeState.selectedRole) return;
+        if (runtimeState.selectedRole !== 'admin') {
+          actions.updateRuntimeState({ tourRequested: true, tourType: 'tools' });
+        }
+        actions.complete();
+        break;
+      case 'launch-admin':
+        actions.updateRuntimeState({ tourRequested: true, tourType: 'admin' });
+        actions.complete();
+        break;
+      case 'launch-tools':
+        actions.updateRuntimeState({ tourRequested: true, tourType: 'tools' });
+        actions.complete();
+        break;
+      case 'launch-auto': {
+        const tourType = serverExperience.effectiveIsAdmin || runtimeState.selectedRole === 'admin' ? 'admin' : 'tools';
+        actions.updateRuntimeState({ tourRequested: true, tourType });
+        actions.complete();
+        break;
+      }
+      case 'skip-to-license':
+        markStepSeen('tour');
+        actions.updateRuntimeState({ tourRequested: false });
+        actions.complete();
+        break;
+      case 'see-plans':
+        actions.complete();
+        navigate('/settings/adminPlan');
+        break;
+    }
+  }, [actions, handleDownloadSelected, navigate, runtimeState.selectedRole, serverExperience.effectiveIsAdmin]);
+
+  const isRTL = typeof document !== 'undefined' ? document.documentElement.dir === 'rtl' : false;
+  const [isTourOpen, setIsTourOpen] = useState(false);
+
+  useEffect(() => dispatchTourState(isTourOpen), [isTourOpen]);
+
+  const { openFilesModal, closeFilesModal } = useFilesModalContext();
+  const tourOrch = useTourOrchestration();
+  const adminTourOrch = useAdminTourOrchestration();
+
+  const userStepsConfig = useMemo(
+    () => createUserStepsConfig({
+      t,
+      actions: {
+        saveWorkbenchState: tourOrch.saveWorkbenchState,
+        closeFilesModal,
+        backToAllTools: tourOrch.backToAllTools,
+        selectCropTool: tourOrch.selectCropTool,
+        loadSampleFile: tourOrch.loadSampleFile,
+        switchToViewer: tourOrch.switchToViewer,
+        switchToPageEditor: tourOrch.switchToPageEditor,
+        switchToActiveFiles: tourOrch.switchToActiveFiles,
+        selectFirstFile: tourOrch.selectFirstFile,
+        pinFile: tourOrch.pinFile,
+        modifyCropSettings: tourOrch.modifyCropSettings,
+        executeTool: tourOrch.executeTool,
+        openFilesModal,
+      },
+    }),
+    [t, tourOrch, closeFilesModal, openFilesModal]
+  );
+
+  const adminStepsConfig = useMemo(
+    () => createAdminStepsConfig({
+      t,
+      actions: {
+        saveAdminState: adminTourOrch.saveAdminState,
+        openConfigModal: adminTourOrch.openConfigModal,
+        navigateToSection: adminTourOrch.navigateToSection,
+        scrollNavToSection: adminTourOrch.scrollNavToSection,
+      },
+    }),
+    [t, adminTourOrch]
+  );
+
+  const tourSteps = useMemo<StepType[]>(() => {
+    const config = runtimeState.tourType === 'admin' ? adminStepsConfig : userStepsConfig;
+    return Object.values(config);
+  }, [adminStepsConfig, runtimeState.tourType, userStepsConfig]);
+
+  useEffect(() => {
+    if (currentStep?.id === 'tour' && !isTourOpen) {
+      markStepSeen('tour');
+      setIsTourOpen(true);
+    }
+  }, [currentStep, isTourOpen, activeFlow]);
+
+  useEffect(() => {
+    if (externalTourRequested) {
+      actions.updateRuntimeState({ tourRequested: true, tourType: requestedTourType });
+      markStepSeen('tour');
+      setIsTourOpen(true);
+      clearTourRequest();
+    }
+  }, [externalTourRequested, requestedTourType, actions, clearTourRequest]);
+
+  useEffect(() => {
+    if (!isTourOpen) removeAllGlows();
+    return () => removeAllGlows();
+  }, [isTourOpen]);
+
+  const finishTour = useCallback(() => {
+    setIsTourOpen(false);
+    if (runtimeState.tourType === 'admin') {
+      adminTourOrch.restoreAdminState();
+    } else {
+      tourOrch.restoreWorkbenchState();
+    }
+    markStepSeen('tour');
+    if (currentStep?.id === 'tour') actions.complete();
+  }, [actions, adminTourOrch, currentStep?.id, runtimeState.tourType, tourOrch]);
+
+  const handleAdvanceTour = useCallback((args: AdvanceArgs) => {
+    const { setCurrentStep, currentStep: tourCurrentStep, steps, setIsOpen } = args;
+    if (steps && tourCurrentStep === steps.length - 1) {
+      setIsOpen(false);
+      finishTour();
+    } else if (steps) {
+      setCurrentStep((s) => (s === steps.length - 1 ? 0 : s + 1));
+    }
+  }, [finishTour]);
+
+  const handleCloseTour = useCallback((args: CloseArgs) => {
+    args.setIsOpen(false);
+    finishTour();
+  }, [finishTour]);
+
+  const currentSlideDefinition = useMemo(() => {
+    if (!currentStep || currentStep.type !== 'modal-slide' || !currentStep.slideId) {
+      return null;
+    }
+    return SLIDE_DEFINITIONS[currentStep.slideId as SlideId];
+  }, [currentStep]);
+
+  const currentSlideContent = useMemo(() => {
+    if (!currentSlideDefinition) return null;
+    return currentSlideDefinition.createSlide({
+      osLabel: osInfo.label,
+      osUrl: osInfo.url,
+      osOptions,
+      onDownloadUrlChange: setSelectedDownloadUrl,
+      selectedRole: runtimeState.selectedRole,
+      onRoleSelect: handleRoleSelect,
+      licenseNotice: runtimeState.licenseNotice,
+      loginEnabled: serverExperience.loginEnabled,
+      firstLoginUsername: runtimeState.firstLoginUsername,
+      onPasswordChanged: handlePasswordChanged,
+      usingDefaultCredentials: runtimeState.usingDefaultCredentials,
+    });
+  }, [currentSlideDefinition, osInfo, osOptions, runtimeState.selectedRole, runtimeState.licenseNotice, handleRoleSelect, serverExperience.loginEnabled, setSelectedDownloadUrl, runtimeState.firstLoginUsername, handlePasswordChanged]);
+
+  const modalSlideCount = useMemo(() => {
+    return activeFlow.filter((step) => step.type === 'modal-slide').length;
+  }, [activeFlow]);
+
+  const currentModalSlideIndex = useMemo(() => {
+    if (!currentStep || currentStep.type !== 'modal-slide') return 0;
+    const modalSlides = activeFlow.filter((step) => step.type === 'modal-slide');
+    return modalSlides.findIndex((step) => step.id === currentStep.id);
+  }, [activeFlow, currentStep]);
+
+  if (onAuthRoute) {
+    return null;
+  }
+
+  if (showLicenseSlide) {
+    const slideDefinition = SLIDE_DEFINITIONS['server-license'];
+    const effectiveLicenseNotice = externalLicenseNotice || runtimeState.licenseNotice;
+    const slideContent = slideDefinition.createSlide({
+      osLabel: '',
+      osUrl: '',
+      osOptions: [],
+      onDownloadUrlChange: () => {},
+      selectedRole: null,
+      onRoleSelect: () => {},
+      licenseNotice: effectiveLicenseNotice,
+      loginEnabled: serverExperience.loginEnabled,
+    });
+    
+    return (
+      <OnboardingModalSlide
+        slideDefinition={slideDefinition}
+        slideContent={slideContent}
+        runtimeState={{ ...runtimeState, licenseNotice: effectiveLicenseNotice }}
+        modalSlideCount={1}
+        currentModalSlideIndex={0}
+        onSkip={closeLicenseSlide}
+        onAction={(action) => {
+          if (action === 'see-plans') {
+            closeLicenseSlide();
+            navigate('/settings/adminPlan');
+          } else {
+            closeLicenseSlide();
+          }
+        }}
+      />
+    );
+  }
+
+  if (isLoading || !isActive || !currentStep) {
+    return (
+      <OnboardingTour
+        isOpen={isTourOpen}
+        tourSteps={tourSteps}
+        tourType={runtimeState.tourType}
+        isRTL={isRTL}
+        t={t}
+        onAdvance={handleAdvanceTour}
+        onClose={handleCloseTour}
+      />
+    );
+  }
+
+  switch (currentStep.type) {
+    case 'tool-prompt':
+      return <ToolPanelModePrompt forceOpen={true} onComplete={actions.complete} />;
+
+    case 'tour':
+      return (
+        <OnboardingTour
+          isOpen={true}
+          tourSteps={tourSteps}
+          tourType={runtimeState.tourType}
+          isRTL={isRTL}
+          t={t}
+          onAdvance={handleAdvanceTour}
+          onClose={handleCloseTour}
+        />
+      );
+
+    case 'analytics-modal':
+      return <AdminAnalyticsChoiceModal opened={true} onClose={actions.complete} />;
+
+    case 'modal-slide':
+      if (!currentSlideDefinition || !currentSlideContent) return null;
+      return (
+        <OnboardingModalSlide
+          slideDefinition={currentSlideDefinition}
+          slideContent={currentSlideContent}
+          runtimeState={runtimeState}
+          modalSlideCount={modalSlideCount}
+          currentModalSlideIndex={currentModalSlideIndex}
+          onSkip={actions.skip}
+          onAction={handleButtonAction}
+        />
+      );
+
+    default:
+      return null;
+  }
+}
@@ -1,33 +1,44 @@
+/**
+ * OnboardingModalSlide Component
+ * 
+ * Renders a single modal slide in the onboarding flow.
+ * Handles the hero image, content, stepper, and button actions.
+ */
+
 import React from 'react';
 import { Modal, Stack } from '@mantine/core';
 import DiamondOutlinedIcon from '@mui/icons-material/DiamondOutlined';
-import LocalIcon from '@app/components/shared/LocalIcon';
+
+import type { SlideDefinition, ButtonAction } from '@app/components/onboarding/onboardingFlowConfig';
+import type { OnboardingRuntimeState } from '@app/components/onboarding/orchestrator/onboardingConfig';
+import type { SlideConfig } from '@app/types/types';
 import AnimatedSlideBackground from '@app/components/onboarding/slides/AnimatedSlideBackground';
 import OnboardingStepper from '@app/components/onboarding/OnboardingStepper';
-import { renderButtons } from '@app/components/onboarding/InitialOnboardingModal/renderButtons';
-import styles from '@app/components/onboarding/InitialOnboardingModal/InitialOnboardingModal.module.css';
-import type { InitialOnboardingModalProps } from '@app/components/onboarding/InitialOnboardingModal/types';
-import { useInitialOnboardingState } from '@app/components/onboarding/InitialOnboardingModal/useInitialOnboardingState';
+import { SlideButtons } from '@app/components/onboarding/InitialOnboardingModal/renderButtons';
+import LocalIcon from '@app/components/shared/LocalIcon';
 import { BASE_PATH } from '@app/constants/app';
 import { Z_INDEX_OVER_FULLSCREEN_SURFACE } from '@app/styles/zIndex';
+import styles from '@app/components/onboarding/InitialOnboardingModal/InitialOnboardingModal.module.css';

-export default function InitialOnboardingModal(props: InitialOnboardingModalProps) {
-  const flow = useInitialOnboardingState(props);
+interface OnboardingModalSlideProps {
+  slideDefinition: SlideDefinition;
+  slideContent: SlideConfig;
+  runtimeState: OnboardingRuntimeState;
+  modalSlideCount: number;
+  currentModalSlideIndex: number;
+  onSkip: () => void;
+  onAction: (action: ButtonAction) => void;
+}

-  if (!flow) {
-    return null;
-  }
-
-  const {
-    state,
-    totalSteps,
-    currentSlide,
-    slideDefinition,
-    licenseNotice,
-    flowState,
-    closeAndMarkSeen,
-    handleButtonAction,
-  } = flow;
+export default function OnboardingModalSlide({
+  slideDefinition,
+  slideContent,
+  runtimeState,
+  modalSlideCount,
+  currentModalSlideIndex,
+  onSkip,
+  onAction,
+}: OnboardingModalSlideProps) {

  const renderHero = () => {
    if (slideDefinition.hero.type === 'dual-icon') {
@@ -48,6 +59,9 @@ export default function InitialOnboardingModal(props: InitialOnboardingModalProp
        {slideDefinition.hero.type === 'shield' && (
          <LocalIcon icon="verified-user-outline" width={64} height={64} className={styles.heroIcon} />
        )}
+        {slideDefinition.hero.type === 'lock' && (
+          <LocalIcon icon="lock-outline" width={64} height={64} className={styles.heroIcon} />
+        )}
        {slideDefinition.hero.type === 'diamond' && <DiamondOutlinedIcon sx={{ fontSize: 64, color: '#000000' }} />}
        {slideDefinition.hero.type === 'logo' && (
          <img src={`${BASE_PATH}/branding/StirlingPDFLogoNoTextLightHC.svg`} alt="Stirling logo" />
@@ -58,8 +72,8 @@ export default function InitialOnboardingModal(props: InitialOnboardingModalProp

  return (
    <Modal
-      opened={props.opened}
-      onClose={closeAndMarkSeen}
+      opened={true}
+      onClose={onSkip}
      closeOnClickOutside={false}
      centered
      size="lg"
@@ -67,48 +81,48 @@ export default function InitialOnboardingModal(props: InitialOnboardingModalProp
      withCloseButton={false}
      zIndex={Z_INDEX_OVER_FULLSCREEN_SURFACE}
      styles={{
-        body: { padding: 0 },
-        content: { overflow: 'hidden', border: 'none', background: 'var(--bg-surface)' },
+        body: { padding: 0, maxHeight: '90vh', overflow: 'hidden' },
+        content: { overflow: 'hidden', border: 'none', background: 'var(--bg-surface)', maxHeight: '90vh' },
      }}
    >
      <Stack gap={0} className={styles.modalContent}>
        <div className={styles.heroWrapper}>
          <AnimatedSlideBackground
-            gradientStops={currentSlide.background.gradientStops}
-            circles={currentSlide.background.circles}
+            gradientStops={slideContent.background.gradientStops}
+            circles={slideContent.background.circles}
            isActive
-            slideKey={currentSlide.key}
+            slideKey={slideContent.key}
          />
-          <div className={styles.heroLogo} key={`logo-${currentSlide.key}`}>
+          <div className={styles.heroLogo} key={`logo-${slideContent.key}`}>
            {renderHero()}
          </div>
        </div>

-        <div className={styles.modalBody}>
+        <div className={styles.modalBody} style={{ overflowY: 'auto', maxHeight: 'calc(90vh - 220px)' }}>
          <Stack gap={16}>
            <div
-              key={`title-${currentSlide.key}`}
+              key={`title-${slideContent.key}`}
              className={`${styles.title} ${styles.titleText}`}
            >
-              {currentSlide.title}
+              {slideContent.title}
            </div>

            <div className={styles.bodyText}>
-              <div key={`body-${currentSlide.key}`} className={`${styles.bodyCopy} ${styles.bodyCopyInner}`}>
-                {currentSlide.body}
+              <div key={`body-${slideContent.key}`} className={`${styles.bodyCopy} ${styles.bodyCopyInner}`}>
+                {slideContent.body}
              </div>
              <style>{`div strong{color: var(--onboarding-title); font-weight: 600;}`}</style>
            </div>

-            <OnboardingStepper totalSteps={totalSteps} activeStep={state.step} />
+            <OnboardingStepper totalSteps={modalSlideCount} activeStep={currentModalSlideIndex} />

            <div className={styles.buttonContainer}>
-              {renderButtons({
-                slideDefinition,
-                licenseNotice,
-                flowState,
-                onAction: handleButtonAction,
-              })}
+              <SlideButtons
+                slideDefinition={slideDefinition}
+                licenseNotice={runtimeState.licenseNotice}
+                flowState={{ selectedRole: runtimeState.selectedRole }}
+                onAction={onAction}
+              />
            </div>
          </Stack>
        </div>
@@ -1,231 +1,151 @@
-import React, { useEffect, useMemo } from "react";
-import { TourProvider, type StepType } from '@reactour/tour';
-import { useTranslation } from 'react-i18next';
+/**
+ * OnboardingTour Component
+ * 
+ * Reusable tour wrapper that encapsulates all Reactour configuration.
+ * Used by the main Onboarding component for both the 'tour' step and
+ * when the tour is open but onboarding is inactive.
+ */
+
+import React from 'react';
+import { TourProvider, useTour, type StepType } from '@reactour/tour';
 import { CloseButton, ActionIcon } from '@mantine/core';
 import ArrowForwardIcon from '@mui/icons-material/ArrowForward';
-import CheckIcon from '@mui/icons-material/Check';
-import InitialOnboardingModal from '@app/components/onboarding/InitialOnboardingModal';
-import ServerLicenseModal from '@app/components/onboarding/ServerLicenseModal';
-import '@app/components/onboarding/OnboardingTour.css';
-import ToolPanelModePrompt from '@app/components/tools/ToolPanelModePrompt';
-import { useFilesModalContext } from '@app/contexts/FilesModalContext';
-import { useTourOrchestration } from '@app/contexts/TourOrchestrationContext';
-import { useAdminTourOrchestration } from '@app/contexts/AdminTourOrchestrationContext';
-import { useOnboardingFlow } from '@app/components/onboarding/hooks/useOnboardingFlow';
-import { createUserStepsConfig } from '@app/components/onboarding/userStepsConfig';
-import { createAdminStepsConfig } from '@app/components/onboarding/adminStepsConfig';
-import { removeAllGlows } from '@app/components/onboarding/tourGlow';
-import TourContent from '@app/components/onboarding/TourContent';
 import ArrowBackIcon from '@mui/icons-material/ArrowBack';
-import '@app/components/onboarding/OnboardingTour.css';
-import i18n from "@app/i18n";
+import CheckIcon from '@mui/icons-material/Check';
+import type { TFunction } from 'i18next';
+import i18n from '@app/i18n';

-export default function OnboardingTour() {
-  const { t } = useTranslation();
-  const flow = useOnboardingFlow();
-  const { openFilesModal, closeFilesModal } = useFilesModalContext();
-  const {
-    saveWorkbenchState,
-    restoreWorkbenchState,
-    backToAllTools,
-    selectCropTool,
-    loadSampleFile,
-    switchToViewer,
-    switchToPageEditor,
-    switchToActiveFiles,
-    selectFirstFile,
-    pinFile,
-    modifyCropSettings,
-    executeTool,
-  } = useTourOrchestration();
-  const {
-    saveAdminState,
-    restoreAdminState,
-    openConfigModal,
-    navigateToSection,
-    scrollNavToSection,
-  } = useAdminTourOrchestration();
+/**
+ * TourContent - Controls the tour visibility
+ * Syncs the forceOpen prop with the reactour tour state.
+ */
+function TourContent({ forceOpen = false }: { forceOpen?: boolean }) {
+  const { setIsOpen, setCurrentStep } = useTour();
+  const previousIsOpenRef = React.useRef(forceOpen);

-  const isRTL = typeof document !== 'undefined' ? document.documentElement.dir === 'rtl' : false;
+  React.useEffect(() => {
+    const wasClosedNowOpen = !previousIsOpenRef.current && forceOpen;
+    previousIsOpenRef.current = forceOpen;

-  useEffect(() => {
-    if (!flow.isTourOpen) {
-      removeAllGlows();
+    if (wasClosedNowOpen) {
+      setCurrentStep(0);
    }
-    return () => removeAllGlows();
-  }, [flow.isTourOpen]);
+    setIsOpen(forceOpen);
+  }, [forceOpen, setIsOpen, setCurrentStep]);

-  const userStepsConfig = useMemo(
-    () =>
-      createUserStepsConfig({
-        t,
-        actions: {
-          saveWorkbenchState,
-          closeFilesModal,
-          backToAllTools,
-          selectCropTool,
-          loadSampleFile,
-          switchToViewer,
-          switchToPageEditor,
-          switchToActiveFiles,
-          selectFirstFile,
-          pinFile,
-          modifyCropSettings,
-          executeTool,
-          openFilesModal,
-        },
-      }),
-    [
-      t,
-      backToAllTools,
-      closeFilesModal,
-      executeTool,
-      loadSampleFile,
-      modifyCropSettings,
-      openFilesModal,
-      pinFile,
-      saveWorkbenchState,
-      selectCropTool,
-      selectFirstFile,
-      switchToActiveFiles,
-      switchToPageEditor,
-      switchToViewer,
-    ],
-  );
+  return null;
+}

-  const adminStepsConfig = useMemo(
-    () =>
-      createAdminStepsConfig({
-        t,
-        actions: {
-          saveAdminState,
-          openConfigModal,
-          navigateToSection,
-          scrollNavToSection,
-        },
-      }),
-    [navigateToSection, openConfigModal, saveAdminState, scrollNavToSection, t],
-  );
+interface AdvanceArgs {
+  setCurrentStep: (value: number | ((prev: number) => number)) => void;
+  currentStep: number;
+  steps?: StepType[];
+  setIsOpen: (value: boolean) => void;
+}

-  const steps = useMemo<StepType[]>(() => {
-    const config = flow.tourType === 'admin' ? adminStepsConfig : userStepsConfig;
-    return Object.values(config);
-  }, [adminStepsConfig, flow.tourType, userStepsConfig]);
+interface CloseArgs {
+  setIsOpen: (value: boolean) => void;
+}

-  const advanceTour = ({
-    setCurrentStep,
-    currentStep,
-    steps,
-    setIsOpen,
-  }: {
-    setCurrentStep: (value: number | ((prev: number) => number)) => void;
-    currentStep: number;
-    steps?: StepType[];
-    setIsOpen: (value: boolean) => void;
-  }) => {
-    if (steps && currentStep === steps.length - 1) {
-      setIsOpen(false);
-      if (flow.tourType === 'admin') {
-        restoreAdminState();
-      } else {
-        restoreWorkbenchState();
-      }
-      flow.handleTourCompletion();
-    } else if (steps) {
-      setCurrentStep((s) => (s === steps.length - 1 ? 0 : s + 1));
-    }
-  };
+interface OnboardingTourProps {
+  tourSteps: StepType[];
+  tourType: 'admin' | 'tools';
+  isRTL: boolean;
+  t: TFunction;
+  isOpen: boolean;
+  onAdvance: (args: AdvanceArgs) => void;
+  onClose: (args: CloseArgs) => void;
+}

-  const handleCloseTour = ({ setIsOpen }: { setIsOpen: (value: boolean) => void }) => {
-    setIsOpen(false);
-    if (flow.tourType === 'admin') {
-      restoreAdminState();
-    } else {
-      restoreWorkbenchState();
-    }
-    flow.handleTourCompletion();
-  };
+export default function OnboardingTour({
+  tourSteps,
+  tourType,
+  isRTL,
+  t,
+  isOpen,
+  onAdvance,
+  onClose,
+}: OnboardingTourProps) {
+  if (!isOpen) return null;

  return (
-    <>
-      <InitialOnboardingModal {...flow.initialModalProps} />
-      <ToolPanelModePrompt onComplete={flow.handleToolPromptComplete} />
-      <TourProvider
-        key={`${flow.tourType}-${i18n.language}`}
-        steps={steps}
-        maskClassName={flow.maskClassName}
-        onClickClose={handleCloseTour}
-        onClickMask={advanceTour}
-        onClickHighlighted={(e, clickProps) => {
-          e.stopPropagation();
-          advanceTour(clickProps);
-        }}
-        keyboardHandler={(e, clickProps, status) => {
-          if (e.key === 'ArrowRight' && !status?.isRightDisabled && clickProps) {
-            e.preventDefault();
-            advanceTour(clickProps);
-          } else if (e.key === 'Escape' && !status?.isEscDisabled && clickProps) {
-            e.preventDefault();
-            handleCloseTour(clickProps);
-          }
-        }}
-        rtl={isRTL}
-        styles={{
-          popover: (base) => ({
-            ...base,
-            backgroundColor: 'var(--mantine-color-body)',
-            color: 'var(--mantine-color-text)',
-            borderRadius: '8px',
-            padding: '20px',
-            boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
-            maxWidth: '400px',
-          }),
-          maskArea: (base) => ({
-            ...base,
-            rx: 8,
-          }),
-          badge: (base) => ({
-            ...base,
-            backgroundColor: 'var(--mantine-primary-color-filled)',
-          }),
-          controls: (base) => ({
-            ...base,
-            justifyContent: 'center',
-          }),
-        }}
-        highlightedMaskClassName="tour-highlight-glow"
-        showNavigation={true}
-        showBadge={false}
-        showCloseButton={true}
-        disableInteraction={true}
-        disableDotsNavigation={false}
-        prevButton={() => null}
-        nextButton={({ currentStep, stepsLength, setCurrentStep, setIsOpen }) => {
-          const isLast = currentStep === stepsLength - 1;
-          const ArrowIcon = isRTL ? ArrowBackIcon : ArrowForwardIcon;
-          return (
-            <ActionIcon
-              onClick={() => advanceTour({ setCurrentStep, currentStep, steps, setIsOpen })}
-              variant="subtle"
-              size="lg"
-              aria-label={isLast ? t('onboarding.finish', 'Finish') : t('onboarding.next', 'Next')}
-            >
-              {isLast ? <CheckIcon /> : <ArrowIcon />}
-            </ActionIcon>
-          );
-        }}
-        components={{
-          Close: ({ onClick }) => (
-            <CloseButton onClick={onClick} size="md" style={{ position: 'absolute', top: '8px', right: '8px' }} />
-          ),
-          Content: ({ content }: { content: string }) => (
-            <div style={{ paddingRight: '16px' }} dangerouslySetInnerHTML={{ __html: content }} />
-          ),
-        }}
-      >
-        <TourContent />
-      </TourProvider>
-      <ServerLicenseModal {...flow.serverLicenseModalProps} />
-    </>
+    <TourProvider
+      key={`${tourType}-${i18n.language}`}
+      steps={tourSteps}
+      maskClassName={tourType === 'admin' ? 'admin-tour-mask' : undefined}
+      onClickClose={onClose}
+      onClickMask={onAdvance}
+      onClickHighlighted={(e, clickProps) => {
+        e.stopPropagation();
+        onAdvance(clickProps);
+      }}
+      keyboardHandler={(e, clickProps, status) => {
+        if (e.key === 'ArrowRight' && !status?.isRightDisabled && clickProps) {
+          e.preventDefault();
+          onAdvance(clickProps);
+        } else if (e.key === 'Escape' && !status?.isEscDisabled && clickProps) {
+          e.preventDefault();
+          onClose(clickProps);
+        }
+      }}
+      rtl={isRTL}
+      styles={{
+        popover: (base) => ({
+          ...base,
+          backgroundColor: 'var(--mantine-color-body)',
+          color: 'var(--mantine-color-text)',
+          borderRadius: '8px',
+          padding: '20px',
+          boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
+          maxWidth: '400px',
+        }),
+        maskArea: (base) => ({
+          ...base,
+          rx: 8,
+        }),
+        badge: (base) => ({
+          ...base,
+          backgroundColor: 'var(--mantine-primary-color-filled)',
+        }),
+        controls: (base) => ({
+          ...base,
+          justifyContent: 'center',
+        }),
+      }}
+      highlightedMaskClassName="tour-highlight-glow"
+      showNavigation={true}
+      showBadge={false}
+      showCloseButton={true}
+      disableInteraction={true}
+      disableDotsNavigation={false}
+      prevButton={() => null}
+      nextButton={({ currentStep: tourCurrentStep, stepsLength, setCurrentStep, setIsOpen }) => {
+        const isLast = tourCurrentStep === stepsLength - 1;
+        const ArrowIcon = isRTL ? ArrowBackIcon : ArrowForwardIcon;
+        return (
+          <ActionIcon
+            onClick={() => onAdvance({ setCurrentStep, currentStep: tourCurrentStep, steps: tourSteps, setIsOpen })}
+            variant="subtle"
+            size="lg"
+            aria-label={isLast ? t('onboarding.finish', 'Finish') : t('onboarding.next', 'Next')}
+          >
+            {isLast ? <CheckIcon /> : <ArrowIcon />}
+          </ActionIcon>
+        );
+      }}
+      components={{
+        Close: ({ onClick }) => (
+          <CloseButton onClick={onClick} size="md" style={{ position: 'absolute', top: '8px', right: '8px' }} />
+        ),
+        Content: ({ content }: { content: string }) => (
+          <div style={{ paddingRight: '16px' }} dangerouslySetInnerHTML={{ __html: content }} />
+        ),
+      }}
+    >
+      <TourContent forceOpen={true} />
+    </TourProvider>
  );
 }
+
+export type { AdvanceArgs, CloseArgs };
+
@@ -1,120 +0,0 @@
-import React from 'react';
-import { Modal, Button, Group, Stack } from '@mantine/core';
-import { useTranslation } from 'react-i18next';
-import AnimatedSlideBackground from '@app/components/onboarding/slides/AnimatedSlideBackground';
-import ServerLicenseSlide from '@app/components/onboarding/slides/ServerLicenseSlide';
-import { LicenseNotice } from '@app/types/types';
-import { Z_INDEX_OVER_FULLSCREEN_SURFACE } from '@app/styles/zIndex';
-import { BASE_PATH } from '@app/constants/app';
-import styles from '@app/components/onboarding/InitialOnboardingModal/InitialOnboardingModal.module.css';
-
-interface ServerLicenseModalProps {
-  opened: boolean;
-  onClose: () => void;
-  onSeePlans?: () => void;
-  licenseNotice: LicenseNotice;
-}
-
-export default function ServerLicenseModal({
-  opened,
-  onClose,
-  onSeePlans,
-  licenseNotice,
-}: ServerLicenseModalProps) {
-  const { t } = useTranslation();
-  const slide = React.useMemo(() => ServerLicenseSlide({ licenseNotice }), [licenseNotice]);
-  const primaryLabel = licenseNotice.isOverLimit
-    ? t('onboarding.serverLicense.upgrade', 'Upgrade now →')
-    : t('onboarding.serverLicense.seePlans', 'See Plans →');
-  const secondaryLabel = t('onboarding.serverLicense.skip', 'Skip for now');
-
-  const handleSeePlans = () => {
-    onSeePlans?.();
-    onClose();
-  };
-
-  const secondaryStyles = {
-    root: {
-      background: 'var(--onboarding-secondary-button-bg)',
-      border: '1px solid var(--onboarding-secondary-button-border)',
-      color: 'var(--onboarding-secondary-button-text)',
-    },
-  };
-
-  const primaryStyles = {
-    root: {
-      background: 'var(--onboarding-primary-button-bg)',
-      color: 'var(--onboarding-primary-button-text)',
-    },
-  };
-
-  return (
-    <Modal
-      opened={opened}
-      onClose={onClose}
-      centered
-      size="lg"
-      radius="lg"
-      withCloseButton={false}
-      zIndex={Z_INDEX_OVER_FULLSCREEN_SURFACE}
-      styles={{
-        body: { padding: 0 },
-        content: { overflow: 'hidden', border: 'none', background: 'var(--bg-surface)' },
-      }}
-    >
-      <Stack gap={0}>
-        <div className={styles.heroWrapper}>
-          <AnimatedSlideBackground
-            gradientStops={slide.background.gradientStops}
-            circles={slide.background.circles}
-            isActive
-            slideKey={slide.key}
-          />
-          <div className={styles.heroLogo}>
-            <div className={styles.heroIconsContainer}>
-              <div className={styles.iconWrapper}>
-                <img src={`${BASE_PATH}/modern-logo/logo512.png`} alt="Stirling icon" className={styles.downloadIcon} />
-              </div>
-            </div>
-          </div>
-        </div>
-
-        <div style={{ padding: 24 }}>
-          <Stack gap={16}>
-            <div
-              className={styles.title}
-              style={{
-                fontFamily: 'Inter, system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif',
-                fontWeight: 600,
-                fontSize: 22,
-                color: 'var(--onboarding-title)',
-              }}
-            >
-              {slide.title}
-            </div>
-            <div
-              className={styles.bodyCopy}
-              style={{
-                fontFamily: 'Inter, system-ui, -apple-system, Segoe UI, Roboto, Arial, sans-serif',
-                fontSize: 16,
-                color: 'var(--onboarding-body)',
-                lineHeight: 1.5,
-              }}
-            >
-              {slide.body}
-            </div>
-            <Group justify="space-between">
-              <Button styles={secondaryStyles} onClick={onClose}>
-                {secondaryLabel}
-              </Button>
-              <Button styles={primaryStyles} onClick={handleSeePlans}>
-                {primaryLabel}
-              </Button>
-            </Group>
-          </Stack>
-        </div>
-      </Stack>
-    </Modal>
-  );
-}
-
@@ -1,22 +0,0 @@
-import React from 'react';
-import { useTour } from '@reactour/tour';
-import { useOnboarding } from '@app/contexts/OnboardingContext';
-
-export default function TourContent() {
-  const { isOpen } = useOnboarding();
-  const { setIsOpen, setCurrentStep } = useTour();
-  const previousIsOpenRef = React.useRef(isOpen);
-
-  React.useEffect(() => {
-    const wasClosedNowOpen = !previousIsOpenRef.current && isOpen;
-    previousIsOpenRef.current = isOpen;
-
-    if (wasClosedNowOpen) {
-      setCurrentStep(0);
-    }
-    setIsOpen(isOpen);
-  }, [isOpen, setIsOpen, setCurrentStep]);
-
-  return null;
-}
-
@@ -1,82 +0,0 @@
-import { Modal, Title, Text, Button, Stack, Group } from '@mantine/core';
-import { useTranslation } from 'react-i18next';
-import { Z_INDEX_OVER_FULLSCREEN_SURFACE } from '@app/styles/zIndex';
-
-interface TourWelcomeModalProps {
-  opened: boolean;
-  onStartTour: () => void;
-  onMaybeLater: () => void;
-  onDontShowAgain: () => void;
-}
-
-export default function TourWelcomeModal({
-  opened,
-  onStartTour,
-  onMaybeLater,
-  onDontShowAgain,
-}: TourWelcomeModalProps) {
-  const { t } = useTranslation();
-
-  return (
-    <Modal
-      opened={opened}
-      onClose={onMaybeLater}
-      centered
-      size="md"
-      radius="lg"
-      withCloseButton={false}
-      zIndex={Z_INDEX_OVER_FULLSCREEN_SURFACE}
-    >
-      <Stack gap="lg">
-        <Stack gap="xs">
-          <Title order={2}>
-            {t('onboarding.welcomeModal.title', 'Welcome to Stirling PDF!')}
-          </Title>
-          <Text size="md" c="dimmed">
-            {t('onboarding.welcomeModal.description',
-              "Would you like to take a quick 1-minute tour to learn the key features and how to get started?"
-            )}
-          </Text>
-          <Text
-            size="md"
-            c="dimmed"
-            dangerouslySetInnerHTML={{
-              __html: t('onboarding.welcomeModal.helpHint',
-                'You can always access this tour later from the <strong>Help</strong> button in the bottom left.'
-              )
-            }}
-          />
-        </Stack>
-
-        <Stack gap="sm">
-          <Button
-            onClick={onStartTour}
-            size="md"
-            variant="filled"
-            fullWidth
-          >
-            {t('onboarding.welcomeModal.startTour', 'Start Tour')}
-          </Button>
-
-          <Group grow>
-            <Button
-              onClick={onMaybeLater}
-              size="md"
-              variant="light"
-            >
-              {t('onboarding.welcomeModal.maybeLater', 'Maybe Later')}
-            </Button>
-
-            <Button
-              onClick={onDontShowAgain}
-              size="md"
-              variant="light"
-            >
-              {t('onboarding.welcomeModal.dontShowAgain', "Don't Show Again")}
-            </Button>
-          </Group>
-        </Stack>
-      </Stack>
-    </Modal>
-  );
-}
@@ -1,8 +1,19 @@
 import type { StepType } from '@reactour/tour';
 import type { TFunction } from 'i18next';
-import { AdminTourStep } from '@app/components/onboarding/tourSteps';
 import { addGlowToElements, removeAllGlows } from '@app/components/onboarding/tourGlow';

+export enum AdminTourStep {
+  WELCOME,
+  CONFIG_BUTTON,
+  SETTINGS_OVERVIEW,
+  TEAMS_AND_USERS,
+  SYSTEM_CUSTOMIZATION,
+  DATABASE_SECTION,
+  CONNECTIONS_SECTION,
+  ADMIN_TOOLS,
+  WRAP_UP,
+}
+
 interface AdminStepActions {  
  saveAdminState: () => void;
  openConfigModal: () => void;
@@ -1,304 +0,0 @@
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import { usePreferences } from '@app/contexts/PreferencesContext';
-import { useAppConfig } from '@app/contexts/AppConfigContext';
-import { useOnboarding } from '@app/contexts/OnboardingContext';
-import type { LicenseNotice } from '@app/types/types';
-import { useNavigate, useLocation } from 'react-router-dom';
-import {
-  ONBOARDING_SESSION_BLOCK_KEY,
-  ONBOARDING_SESSION_EVENT,
-  SERVER_LICENSE_REQUEST_EVENT,
-  type ServerLicenseRequestPayload,
-} from '@app/constants/events';
-import { useServerExperience } from '@app/hooks/useServerExperience';
-
-// Auth routes where onboarding should NOT show
-const AUTH_ROUTES = ['/login', '/signup', '/auth', '/invite'];
-
-// Check if user has an auth token (to avoid flash before redirect)
-function hasAuthToken(): boolean {
-  if (typeof window === 'undefined') return false;
-  return !!localStorage.getItem('stirling_jwt');
-}
-
-interface InitialModalHandlers {
-  opened: boolean;
-  onLicenseNoticeUpdate: (notice: LicenseNotice) => void;
-  onRequestServerLicense: (options?: { deferUntilTourComplete?: boolean; selfReportedAdmin?: boolean }) => void;
-  onClose: () => void;
-}
-
-interface ServerLicenseModalHandlers {
-  opened: boolean;
-  licenseNotice: LicenseNotice;
-  onClose: () => void;
-  onSeePlans: () => void;
-}
-
-export function useOnboardingFlow() {
-  const { preferences, updatePreference } = usePreferences();
-  const { config, loading: configLoading } = useAppConfig();
-  const { completeTour, tourType, isOpen } = useOnboarding();
-  const location = useLocation();
-  
-  // Check if we're on an auth route (login, signup, etc.)
-  const isOnAuthRoute = AUTH_ROUTES.some(route => location.pathname.startsWith(route));
-  
-  // Check if login is enabled but user doesn't have a token
-  // This prevents a flash of the modal before redirect to /login
-  const loginEnabled = config?.enableLogin === true;
-  const isUnauthenticatedWithLoginEnabled = loginEnabled && !hasAuthToken();
-  
-  // Don't show intro onboarding:
-  // 1. On explicit auth routes (/login, /signup, etc.)
-  // 2. While config is still loading
-  // 3. When login is enabled but user isn't authenticated (would redirect to /login)
-  // This ensures:
-  // - If login is enabled: user must be logged in before seeing onboarding
-  // - If login is disabled: homepage must have rendered first
-  const shouldShowIntro = !preferences.hasSeenIntroOnboarding 
-    && !isOnAuthRoute 
-    && !configLoading
-    && !isUnauthenticatedWithLoginEnabled;
-  const isAdminUser = !!config?.isAdmin;
-  const { hasPaidLicense } = useServerExperience();
-
-  const [licenseNotice, setLicenseNotice] = useState<LicenseNotice>({
-    totalUsers: null,
-    freeTierLimit: 5,
-    isOverLimit: false,
-    requiresLicense: false,
-  });
-  const [serverLicenseIntent, setServerLicenseIntent] = useState<'idle' | 'pending' | 'deferred'>('idle');
-  const [serverLicenseSource, setServerLicenseSource] = useState<'config' | 'self-reported' | null>(null);
-  const [isServerLicenseOpen, setIsServerLicenseOpen] = useState(false);
-  const [hasShownServerLicense, setHasShownServerLicense] = useState(false);
-  const [toolPromptCompleted, setToolPromptCompleted] = useState(
-    preferences.toolPanelModePromptSeen || preferences.hasSelectedToolPanelMode,
-  );
-  const introWasOpenRef = useRef(false);
-  const navigate = useNavigate();
-  const onboardingSessionMarkedRef = useRef(false);
-
-  const handleInitialModalClose = useCallback(() => {
-    if (!preferences.hasSeenIntroOnboarding) {
-      updatePreference('hasSeenIntroOnboarding', true);
-    }
-  }, [preferences.hasSeenIntroOnboarding, updatePreference]);
-
-  const handleLicenseNoticeUpdate = useCallback((notice: LicenseNotice) => {
-    setLicenseNotice(notice);
-  }, []);
-
-  const handleToolPromptComplete = useCallback(() => {
-    setToolPromptCompleted(true);
-  }, []);
-
-  const requestServerLicense = useCallback(
-    ({
-      deferUntilTourComplete = false,
-      selfReportedAdmin = false,
-    }: { deferUntilTourComplete?: boolean; selfReportedAdmin?: boolean } = {}) => {
-      const qualifies = isAdminUser || selfReportedAdmin;
-      if (!qualifies) {
-        return;
-      }
-      if (hasPaidLicense || !licenseNotice.requiresLicense) {
-        return;
-      }
-      setServerLicenseSource(isAdminUser ? 'config' : 'self-reported');
-      setServerLicenseIntent((prev) => {
-        if (prev === 'pending') {
-          return prev;
-        }
-        if (prev === 'deferred') {
-          return deferUntilTourComplete ? prev : 'pending';
-        }
-        if (prev === 'idle') {
-          return deferUntilTourComplete ? 'deferred' : 'pending';
-        }
-        return prev;
-      });
-    },
-    [hasPaidLicense, isAdminUser, licenseNotice.requiresLicense],
-  );
-
-  useEffect(() => {
-    if (typeof window === 'undefined') {
-      return;
-    }
-
-    const handleServerLicenseRequested = (event: Event) => {
-      const { detail } = event as CustomEvent<ServerLicenseRequestPayload>;
-
-      if (detail?.licenseNotice) {
-        setLicenseNotice((prev) => ({
-          ...prev,
-          ...detail.licenseNotice,
-          totalUsers:
-            detail.licenseNotice?.totalUsers ?? prev.totalUsers,
-          freeTierLimit:
-            detail.licenseNotice?.freeTierLimit ?? prev.freeTierLimit,
-          isOverLimit:
-            detail.licenseNotice?.isOverLimit ?? prev.isOverLimit,
-          requiresLicense:
-            detail.licenseNotice?.requiresLicense ?? prev.requiresLicense,
-        }));
-      }
-
-      requestServerLicense({
-        deferUntilTourComplete: detail?.deferUntilTourComplete ?? false,
-        selfReportedAdmin: detail?.selfReportedAdmin ?? false,
-      });
-    };
-
-    window.addEventListener(
-      SERVER_LICENSE_REQUEST_EVENT,
-      handleServerLicenseRequested as EventListener,
-    );
-
-    return () => {
-      window.removeEventListener(
-        SERVER_LICENSE_REQUEST_EVENT,
-        handleServerLicenseRequested as EventListener,
-      );
-    };
-  }, [requestServerLicense]);
-
-  useEffect(() => {
-    const isEligibleAdmin =
-      isAdminUser || serverLicenseSource === 'self-reported' || licenseNotice.requiresLicense;
-    if (
-      introWasOpenRef.current &&
-      !shouldShowIntro &&
-      isEligibleAdmin &&
-      toolPromptCompleted &&
-      !hasShownServerLicense &&
-      licenseNotice.requiresLicense &&
-      serverLicenseIntent === 'idle'
-    ) {
-      if (!serverLicenseSource) {
-        setServerLicenseSource(isAdminUser ? 'config' : 'self-reported');
-      }
-      setServerLicenseIntent('pending');
-    }
-    introWasOpenRef.current = shouldShowIntro;
-  }, [
-    hasShownServerLicense,
-    isAdminUser,
-    serverLicenseIntent,
-    shouldShowIntro,
-    serverLicenseSource,
-    toolPromptCompleted,
-    licenseNotice.requiresLicense,
-  ]);
-
-  useEffect(() => {
-    const isEligibleAdmin =
-      isAdminUser || serverLicenseSource === 'self-reported' || licenseNotice.requiresLicense;
-    if (
-      serverLicenseIntent !== 'idle' &&
-      !shouldShowIntro &&
-      !isOpen &&
-      !isServerLicenseOpen &&
-      isEligibleAdmin &&
-      toolPromptCompleted &&
-      licenseNotice.requiresLicense
-    ) {
-      setIsServerLicenseOpen(true);
-      setServerLicenseIntent(serverLicenseIntent === 'deferred' ? 'pending' : 'idle');
-    }
-  }, [
-    isAdminUser,
-    isOpen,
-    isServerLicenseOpen,
-    serverLicenseIntent,
-    shouldShowIntro,
-    serverLicenseSource,
-    toolPromptCompleted,
-    licenseNotice.requiresLicense,
-  ]);
-
-  const handleServerLicenseClose = useCallback(() => {
-    setIsServerLicenseOpen(false);
-    setHasShownServerLicense(true);
-    setServerLicenseIntent('idle');
-    setServerLicenseSource(null);
-  }, []);
-
-  useEffect(() => {
-    if (onboardingSessionMarkedRef.current) {
-      return;
-    }
-    if (typeof window === 'undefined') {
-      return;
-    }
-    if (shouldShowIntro || isOpen) {
-      onboardingSessionMarkedRef.current = true;
-      window.sessionStorage.setItem(ONBOARDING_SESSION_BLOCK_KEY, 'true');
-      window.dispatchEvent(new CustomEvent(ONBOARDING_SESSION_EVENT));
-    }
-  }, [isOpen, shouldShowIntro]);
-
-  useEffect(() => {
-    if (typeof window === 'undefined') {
-      return;
-    }
-    if (!shouldShowIntro && !isOpen) {
-      window.sessionStorage.removeItem(ONBOARDING_SESSION_BLOCK_KEY);
-      window.dispatchEvent(new CustomEvent(ONBOARDING_SESSION_EVENT));
-    }
-  }, [isOpen, shouldShowIntro]);
-
-  const handleServerLicenseSeePlans = useCallback(() => {
-    handleServerLicenseClose();
-    navigate('/settings/adminPlan');
-  }, [handleServerLicenseClose, navigate]);
-
-  const handleTourCompletion = useCallback(() => {
-    completeTour();
-    if (serverLicenseIntent === 'deferred') {
-      setServerLicenseIntent('pending');
-    } else if (tourType === 'admin' && (isAdminUser || serverLicenseSource === 'self-reported')) {
-      setServerLicenseSource((prev) => prev ?? (isAdminUser ? 'config' : 'self-reported'));
-      setServerLicenseIntent((prev) => (prev === 'pending' ? prev : 'pending'));
-    }
-  }, [
-    completeTour,
-    isAdminUser,
-    serverLicenseIntent,
-    serverLicenseSource,
-    tourType,
-  ]);
-
-  const initialModalProps: InitialModalHandlers = useMemo(
-    () => ({
-      opened: shouldShowIntro,
-      onLicenseNoticeUpdate: handleLicenseNoticeUpdate,
-      onRequestServerLicense: requestServerLicense,
-      onClose: handleInitialModalClose,
-    }),
-    [handleInitialModalClose, handleLicenseNoticeUpdate, requestServerLicense, shouldShowIntro],
-  );
-
-  const serverLicenseModalProps: ServerLicenseModalHandlers = useMemo(
-    () => ({
-      opened: isServerLicenseOpen,
-      licenseNotice,
-      onClose: handleServerLicenseClose,
-      onSeePlans: handleServerLicenseSeePlans,
-    }),
-    [handleServerLicenseClose, handleServerLicenseSeePlans, isServerLicenseOpen, licenseNotice],
-  );
-
-  return {
-    tourType,
-    isTourOpen: isOpen,
-    maskClassName: tourType === 'admin' ? 'admin-tour-mask' : undefined,
-    initialModalProps,
-    handleToolPromptComplete,
-    serverLicenseModalProps,
-    handleTourCompletion,
-  };
-}
-
@@ -3,16 +3,18 @@ import DesktopInstallSlide from '@app/components/onboarding/slides/DesktopInstal
 import SecurityCheckSlide from '@app/components/onboarding/slides/SecurityCheckSlide';
 import PlanOverviewSlide from '@app/components/onboarding/slides/PlanOverviewSlide';
 import ServerLicenseSlide from '@app/components/onboarding/slides/ServerLicenseSlide';
+import FirstLoginSlide from '@app/components/onboarding/slides/FirstLoginSlide';
 import { SlideConfig, LicenseNotice } from '@app/types/types';

 export type SlideId =
+  | 'first-login'
  | 'welcome'
  | 'desktop-install'
  | 'security-check'
  | 'admin-overview'
  | 'server-license';

-export type HeroType = 'rocket' | 'dual-icon' | 'shield' | 'diamond' | 'logo';
+export type HeroType = 'rocket' | 'dual-icon' | 'shield' | 'diamond' | 'logo' | 'lock';

 export type ButtonAction =
  | 'next'
@@ -46,6 +48,10 @@ export interface SlideFactoryParams {
  onRoleSelect: (role: 'admin' | 'user' | null) => void;
  licenseNotice?: LicenseNotice;
  loginEnabled?: boolean;
+  // First login params
+  firstLoginUsername?: string;
+  onPasswordChanged?: () => void;
+  usingDefaultCredentials?: boolean;
 }

 export interface HeroDefinition {
@@ -71,6 +77,17 @@ export interface SlideDefinition {
 }

 export const SLIDE_DEFINITIONS: Record<SlideId, SlideDefinition> = {
+  'first-login': {
+    id: 'first-login',
+    createSlide: ({ firstLoginUsername, onPasswordChanged, usingDefaultCredentials }) => 
+      FirstLoginSlide({ 
+        username: firstLoginUsername || '', 
+        onPasswordChanged: onPasswordChanged || (() => {}),
+        usingDefaultCredentials: usingDefaultCredentials || false,
+      }),
+    hero: { type: 'lock' },
+    buttons: [], // Form has its own submit button
+  },
  'welcome': {
    id: 'welcome',
    createSlide: () => WelcomeSlide(),
@@ -197,11 +214,3 @@ export const SLIDE_DEFINITIONS: Record<SlideId, SlideDefinition> = {
  },
 };

-export const FLOW_SEQUENCES = {
-  loginAdmin: ['welcome', 'desktop-install', 'admin-overview'] as SlideId[],
-  loginUser: ['welcome', 'desktop-install'] as SlideId[],
-  noLoginBase: ['welcome', 'desktop-install', 'security-check'] as SlideId[],
-  noLoginAdmin: ['admin-overview'] as SlideId[],
-};
-
-
@@ -0,0 +1,127 @@
+export type OnboardingStepId =
+  | 'first-login'
+  | 'welcome'
+  | 'desktop-install'
+  | 'security-check'
+  | 'admin-overview'
+  | 'tool-layout'
+  | 'tour'
+  | 'server-license'
+  | 'analytics-choice';
+
+export type OnboardingStepType =
+  | 'modal-slide'
+  | 'tool-prompt'
+  | 'tour'
+  | 'analytics-modal';
+
+export interface OnboardingRuntimeState {
+  selectedRole: 'admin' | 'user' | null;
+  tourRequested: boolean;
+  tourType: 'admin' | 'tools';
+  isDesktopApp: boolean;
+  analyticsNotConfigured: boolean;
+  analyticsEnabled: boolean;
+  licenseNotice: {
+    totalUsers: number | null;
+    freeTierLimit: number;
+    isOverLimit: boolean;
+    requiresLicense: boolean;
+  };
+  requiresPasswordChange: boolean;
+  firstLoginUsername: string;
+  usingDefaultCredentials: boolean;
+}
+
+export interface OnboardingConditionContext extends OnboardingRuntimeState {
+  loginEnabled: boolean;
+  effectiveIsAdmin: boolean;
+}
+
+export interface OnboardingStep {
+  id: OnboardingStepId;
+  type: OnboardingStepType;
+  condition: (ctx: OnboardingConditionContext) => boolean;
+  slideId?: 'first-login' | 'welcome' | 'desktop-install' | 'security-check' | 'admin-overview' | 'server-license';
+}
+
+export const DEFAULT_RUNTIME_STATE: OnboardingRuntimeState = {
+  selectedRole: null,
+  tourRequested: false,
+  tourType: 'tools',
+  isDesktopApp: false,
+  analyticsNotConfigured: false,
+  analyticsEnabled: false,
+  licenseNotice: {
+    totalUsers: null,
+    freeTierLimit: 5,
+    isOverLimit: false,
+    requiresLicense: false,
+  },
+  requiresPasswordChange: false,
+  firstLoginUsername: '',
+  usingDefaultCredentials: false,
+};
+
+export const ONBOARDING_STEPS: OnboardingStep[] = [
+  {
+    id: 'first-login',
+    type: 'modal-slide',
+    slideId: 'first-login',
+    condition: (ctx) => ctx.requiresPasswordChange,
+  },
+  {
+    id: 'welcome',
+    type: 'modal-slide',
+    slideId: 'welcome',
+    condition: () => true,
+  },
+  {
+    id: 'desktop-install',
+    type: 'modal-slide',
+    slideId: 'desktop-install',
+    condition: (ctx) => !ctx.isDesktopApp,
+  },
+  {
+    id: 'security-check',
+    type: 'modal-slide',
+    slideId: 'security-check',
+    condition: (ctx) => !ctx.loginEnabled && !ctx.isDesktopApp,
+  },
+  {
+    id: 'admin-overview',
+    type: 'modal-slide',
+    slideId: 'admin-overview',
+    condition: (ctx) => ctx.effectiveIsAdmin,
+  },
+  {
+    id: 'tool-layout',
+    type: 'tool-prompt',
+    condition: () => true,
+  },
+  {
+    id: 'tour',
+    type: 'tour',
+    condition: (ctx) => ctx.tourRequested || !ctx.effectiveIsAdmin,
+  },
+  {
+    id: 'server-license',
+    type: 'modal-slide',
+    slideId: 'server-license',
+    condition: (ctx) => ctx.effectiveIsAdmin && ctx.licenseNotice.requiresLicense,
+  },
+  {
+    id: 'analytics-choice',
+    type: 'analytics-modal',
+    condition: (ctx) => ctx.effectiveIsAdmin && ctx.analyticsNotConfigured,
+  },
+];
+
+export function getStepById(id: OnboardingStepId): OnboardingStep | undefined {
+  return ONBOARDING_STEPS.find((step) => step.id === id);
+}
+
+export function getStepIndex(id: OnboardingStepId): number {
+  return ONBOARDING_STEPS.findIndex((step) => step.id === id);
+}
+
@@ -0,0 +1,97 @@
+import { type OnboardingStepId, ONBOARDING_STEPS } from '@app/components/onboarding/orchestrator/onboardingConfig';
+
+const STORAGE_PREFIX = 'onboarding';
+
+export function getStorageKey(stepId: OnboardingStepId): string {
+  return `${STORAGE_PREFIX}::${stepId}`;
+}
+
+export function hasSeenStep(stepId: OnboardingStepId): boolean {
+  if (typeof window === 'undefined') return false;
+  try {
+    return localStorage.getItem(getStorageKey(stepId)) === 'true';
+  } catch {
+    return false;
+  }
+}
+
+export function markStepSeen(stepId: OnboardingStepId): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.setItem(getStorageKey(stepId), 'true');
+  } catch (error) {
+    console.error('[onboardingStorage] Error marking step as seen:', error);
+  }
+}
+
+export function resetStepSeen(stepId: OnboardingStepId): void {
+  if (typeof window === 'undefined') return;
+  try {
+    localStorage.removeItem(getStorageKey(stepId));
+  } catch (error) {
+    console.error('[onboardingStorage] Error resetting step seen:', error);
+  }
+}
+
+export function resetAllOnboardingProgress(): void {
+  if (typeof window === 'undefined') return;
+  try {
+    const prefix = `${STORAGE_PREFIX}::`;
+    const keysToRemove: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+      const key = localStorage.key(i);
+      if (key?.startsWith(prefix)) keysToRemove.push(key);
+    }
+    keysToRemove.forEach((key) => localStorage.removeItem(key));
+  } catch (error) {
+    console.error('[onboardingStorage] Error resetting all onboarding progress:', error);
+  }
+}
+
+export function getOnboardingStorageState(): Record<string, boolean> {
+  const state: Record<string, boolean> = {};
+  ONBOARDING_STEPS.forEach((step) => {
+    state[step.id] = hasSeenStep(step.id);
+  });
+  return state;
+}
+
+export function migrateFromLegacyPreferences(): void {
+  if (typeof window === 'undefined') return;
+  
+  const migrationKey = `${STORAGE_PREFIX}::migrated`;
+  
+  try {
+    // Skip if already migrated
+    if (localStorage.getItem(migrationKey) === 'true') return;
+    
+    const prefsRaw = localStorage.getItem('stirlingpdf_preferences');
+    if (prefsRaw) {
+      const prefs = JSON.parse(prefsRaw) as Record<string, unknown>;
+      
+      // Migrate based on legacy flags
+      if (prefs.hasSeenIntroOnboarding === true) {
+        markStepSeen('welcome');
+        markStepSeen('desktop-install');
+        markStepSeen('security-check');
+        markStepSeen('admin-overview');
+      }
+      
+      if (prefs.toolPanelModePromptSeen === true || prefs.hasSelectedToolPanelMode === true) {
+        markStepSeen('tool-layout');
+      }
+      
+      if (prefs.hasCompletedOnboarding === true) {
+        markStepSeen('tour');
+        markStepSeen('analytics-choice');
+        markStepSeen('server-license');
+      }
+      
+    }
+    
+    // Mark migration complete
+    localStorage.setItem(migrationKey, 'true');
+  } catch {
+    // If migration fails, onboarding will show again - safer than hiding it
+  }
+}
@@ -0,0 +1,353 @@
+import { useState, useCallback, useMemo, useEffect, useRef } from 'react';
+import { useLocation } from 'react-router-dom';
+import { useServerExperience } from '@app/hooks/useServerExperience';
+import { useAppConfig } from '@app/contexts/AppConfigContext';
+
+import {
+  ONBOARDING_STEPS,
+  type OnboardingStepId,
+  type OnboardingStep,
+  type OnboardingRuntimeState,
+  type OnboardingConditionContext,
+  DEFAULT_RUNTIME_STATE,
+} from '@app/components/onboarding/orchestrator/onboardingConfig';
+import {
+  hasSeenStep,
+  markStepSeen,
+  migrateFromLegacyPreferences,
+} from '@app/components/onboarding/orchestrator/onboardingStorage';
+import { accountService } from '@app/services/accountService';
+
+const AUTH_ROUTES = ['/login', '/signup', '/auth', '/invite'];
+const SESSION_TOUR_REQUESTED = 'onboarding::session::tour-requested';
+const SESSION_TOUR_TYPE = 'onboarding::session::tour-type';
+const SESSION_SELECTED_ROLE = 'onboarding::session::selected-role';
+
+// Check if user has an auth token (to avoid flash before redirect)
+function hasAuthToken(): boolean {
+  if (typeof window === 'undefined') return false;
+  return !!localStorage.getItem('stirling_jwt');
+}
+
+// Get initial runtime state from session storage (survives remounts)
+function getInitialRuntimeState(baseState: OnboardingRuntimeState): OnboardingRuntimeState {
+  if (typeof window === 'undefined') {
+    return baseState;
+  }
+  
+  try {
+    const tourRequested = sessionStorage.getItem(SESSION_TOUR_REQUESTED) === 'true';
+    const tourType = (sessionStorage.getItem(SESSION_TOUR_TYPE) as 'admin' | 'tools') || 'tools';
+    const selectedRole = sessionStorage.getItem(SESSION_SELECTED_ROLE) as 'admin' | 'user' | null;
+    
+    return {
+      ...baseState,
+      tourRequested,
+      tourType,
+      selectedRole,
+    };
+  } catch {
+    return baseState;
+  }
+}
+
+function persistRuntimeState(state: Partial<OnboardingRuntimeState>): void {
+  if (typeof window === 'undefined') return;
+  
+  try {
+    if (state.tourRequested !== undefined) {
+      sessionStorage.setItem(SESSION_TOUR_REQUESTED, state.tourRequested ? 'true' : 'false');
+    }
+    if (state.tourType !== undefined) {
+      sessionStorage.setItem(SESSION_TOUR_TYPE, state.tourType);
+    }
+    if (state.selectedRole !== undefined) {
+      if (state.selectedRole) {
+        sessionStorage.setItem(SESSION_SELECTED_ROLE, state.selectedRole);
+      } else {
+        sessionStorage.removeItem(SESSION_SELECTED_ROLE);
+      }
+    }
+  } catch (error) {
+    console.error('[useOnboardingOrchestrator] Error persisting runtime state:', error);
+  }
+}
+
+function clearRuntimeStateSession(): void {
+  if (typeof window === 'undefined') return;
+  
+  try {
+    sessionStorage.removeItem(SESSION_TOUR_REQUESTED);
+    sessionStorage.removeItem(SESSION_TOUR_TYPE);
+    sessionStorage.removeItem(SESSION_SELECTED_ROLE);
+  } catch {
+    // Ignore errors
+  }
+}
+
+export interface OnboardingOrchestratorState {
+  /** Whether onboarding is currently active */
+  isActive: boolean;
+  /** The current step being shown (null if no step is active) */
+  currentStep: OnboardingStep | null;
+  /** Index of current step in the active flow (for display purposes) */
+  currentStepIndex: number;
+  /** Total number of steps in the active flow */
+  totalSteps: number;
+  /** Runtime state that affects conditions */
+  runtimeState: OnboardingRuntimeState;
+  /** All steps that will be shown in this flow (filtered by conditions) */
+  activeFlow: OnboardingStep[];
+  /** Whether all steps have been seen */
+  isComplete: boolean;
+  /** Whether we're still initializing */
+  isLoading: boolean;
+}
+
+export interface OnboardingOrchestratorActions {
+  /** Move to the next step */
+  next: () => void;
+  /** Move to the previous step */
+  prev: () => void;
+  /** Skip the current step (marks as seen but doesn't complete) */
+  skip: () => void;
+  /** Mark current step as seen and move to next */
+  complete: () => void;
+  /** Update runtime state (e.g., after role selection) */
+  updateRuntimeState: (updates: Partial<OnboardingRuntimeState>) => void;
+  /** Force re-evaluation of the flow (used when conditions change) */
+  refreshFlow: () => void;
+  /** Manually start a specific step (for external triggers) */
+  startStep: (stepId: OnboardingStepId) => void;
+  /** Close/pause onboarding (can be resumed later) */
+  pause: () => void;
+  /** Resume onboarding from where it was paused */
+  resume: () => void;
+}
+
+export interface UseOnboardingOrchestratorResult {
+  state: OnboardingOrchestratorState;
+  actions: OnboardingOrchestratorActions;
+}
+
+export interface UseOnboardingOrchestratorOptions {
+  /** Override the default runtime state (used by desktop to set isDesktopApp: true) */
+  defaultRuntimeState?: OnboardingRuntimeState;
+}
+
+export function useOnboardingOrchestrator(
+  options?: UseOnboardingOrchestratorOptions
+): UseOnboardingOrchestratorResult {
+  const defaultState = options?.defaultRuntimeState ?? DEFAULT_RUNTIME_STATE;
+  const serverExperience = useServerExperience();
+  const { config, loading: configLoading } = useAppConfig();
+  const location = useLocation();
+
+  const [runtimeState, setRuntimeState] = useState<OnboardingRuntimeState>(() => 
+    getInitialRuntimeState(defaultState)
+  );
+  const [isPaused, setIsPaused] = useState(false);
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [currentStepIndex, setCurrentStepIndex] = useState(-1);
+  const migrationDone = useRef(false);
+  const initialIndexSet = useRef(false);
+
+  useEffect(() => {
+    if (!migrationDone.current) {
+      migrateFromLegacyPreferences();
+      migrationDone.current = true;
+    }
+  }, []);
+
+  useEffect(() => {
+    setRuntimeState((prev) => ({
+      ...prev,
+      analyticsEnabled: config?.enableAnalytics === true,
+      analyticsNotConfigured: config?.enableAnalytics == null,
+      licenseNotice: {
+        totalUsers: serverExperience.totalUsers,
+        freeTierLimit: serverExperience.freeTierLimit,
+        isOverLimit: serverExperience.overFreeTierLimit ?? false,
+        requiresLicense: !serverExperience.hasPaidLicense && (
+          serverExperience.overFreeTierLimit === true ||
+          (serverExperience.effectiveIsAdmin && serverExperience.userCountResolved)
+        ),
+      },
+    }));
+  }, [
+    config?.enableAnalytics,
+    serverExperience.totalUsers,
+    serverExperience.freeTierLimit,
+    serverExperience.overFreeTierLimit,
+    serverExperience.hasPaidLicense,
+    serverExperience.effectiveIsAdmin,
+    serverExperience.userCountResolved,
+  ]);
+
+  useEffect(() => {
+    const checkFirstLogin = async () => {
+      if (config?.enableLogin !== true || !hasAuthToken()) return;
+
+      try {
+        const [accountData, loginPageData] = await Promise.all([
+          accountService.getAccountData(),
+          accountService.getLoginPageData(),
+        ]);
+        
+        setRuntimeState((prev) => ({
+          ...prev,
+          requiresPasswordChange: accountData.changeCredsFlag,
+          firstLoginUsername: accountData.username,
+          usingDefaultCredentials: loginPageData.showDefaultCredentials,
+        }));
+      } catch {
+        // Account endpoint failed - user not logged in or security disabled
+      }
+    };
+
+    if (!configLoading) {
+      checkFirstLogin();
+    }
+  }, [config?.enableLogin, configLoading]);
+
+  const isOnAuthRoute = AUTH_ROUTES.some((route) => location.pathname.startsWith(route));
+  const loginEnabled = config?.enableLogin === true;
+  const isUnauthenticatedWithLoginEnabled = loginEnabled && !hasAuthToken();
+  const shouldBlockOnboarding = isOnAuthRoute || configLoading || isUnauthenticatedWithLoginEnabled;
+
+  const conditionContext = useMemo<OnboardingConditionContext>(() => ({
+    ...serverExperience,
+    ...runtimeState,
+    effectiveIsAdmin: serverExperience.effectiveIsAdmin || 
+      (!serverExperience.loginEnabled && runtimeState.selectedRole === 'admin'),
+  }), [serverExperience, runtimeState]);
+
+  const activeFlow = useMemo(() => {
+    return ONBOARDING_STEPS.filter((step) => step.condition(conditionContext));
+  }, [conditionContext]);
+
+  // Wait for config AND admin status before calculating initial step
+  const adminStatusResolved = !configLoading && (
+    config?.enableLogin === false || 
+    config?.enableLogin === undefined || 
+    config?.isAdmin !== undefined
+  );
+  
+  useEffect(() => {
+    if (configLoading || !adminStatusResolved || activeFlow.length === 0) return;
+    
+    let firstUnseenIndex = -1;
+    for (let i = 0; i < activeFlow.length; i++) {
+      if (!hasSeenStep(activeFlow[i].id)) {
+        firstUnseenIndex = i;
+        break;
+      }
+    }
+    
+    if (firstUnseenIndex === -1) {
+      setCurrentStepIndex(activeFlow.length);
+      initialIndexSet.current = true;
+    } else if (!initialIndexSet.current) {
+      setCurrentStepIndex(firstUnseenIndex);
+      initialIndexSet.current = true;
+    }
+  }, [activeFlow, configLoading, adminStatusResolved]);
+
+  const totalSteps = activeFlow.length;
+  
+  const allStepsAlreadySeen = useMemo(() => {
+    if (activeFlow.length === 0) return false;
+    return activeFlow.every(step => hasSeenStep(step.id));
+  }, [activeFlow]);
+  
+  const isComplete = isInitialized && initialIndexSet.current && 
+    (currentStepIndex >= totalSteps || allStepsAlreadySeen);
+  const currentStep = (currentStepIndex >= 0 && currentStepIndex < totalSteps && !allStepsAlreadySeen) 
+    ? activeFlow[currentStepIndex] 
+    : null;
+  const isActive = !shouldBlockOnboarding && !isPaused && !isComplete && isInitialized && currentStep !== null;
+  const isLoading = configLoading || !adminStatusResolved || !isInitialized || 
+    !initialIndexSet.current || (currentStepIndex === -1 && activeFlow.length > 0);
+
+  useEffect(() => {
+    if (!configLoading && !isInitialized) setIsInitialized(true);
+  }, [configLoading, isInitialized]);
+
+  useEffect(() => {
+    if (isComplete) clearRuntimeStateSession();
+  }, [isComplete]);
+
+  const next = useCallback(() => {
+    if (currentStep) markStepSeen(currentStep.id);
+    setCurrentStepIndex((prev) => Math.min(prev + 1, totalSteps));
+  }, [currentStep, totalSteps]);
+
+  const prev = useCallback(() => {
+    setCurrentStepIndex((prev) => Math.max(prev - 1, 0));
+  }, []);
+
+  const skip = useCallback(() => {
+    if (currentStep) markStepSeen(currentStep.id);
+    setCurrentStepIndex((prev) => Math.min(prev + 1, totalSteps));
+  }, [currentStep, totalSteps]);
+
+  const complete = useCallback(() => {
+    if (currentStep) markStepSeen(currentStep.id);
+    setCurrentStepIndex((prev) => Math.min(prev + 1, totalSteps));
+  }, [currentStep, totalSteps]);
+
+  useEffect(() => {
+    if (!currentStep || isLoading) {
+      return;
+    }
+    if (hasSeenStep(currentStep.id)) {
+      complete();
+    }
+  }, [currentStep, isLoading, complete]);
+
+  const updateRuntimeState = useCallback((updates: Partial<OnboardingRuntimeState>) => {
+    persistRuntimeState(updates);
+    setRuntimeState((prev) => ({ ...prev, ...updates }));
+  }, []);
+
+  const refreshFlow = useCallback(() => {
+    initialIndexSet.current = false;
+    setCurrentStepIndex(-1);
+  }, []);
+
+  const startStep = useCallback((stepId: OnboardingStepId) => {
+    const index = activeFlow.findIndex((step) => step.id === stepId);
+    if (index !== -1) {
+      setCurrentStepIndex(index);
+      setIsPaused(false);
+    }
+  }, [activeFlow]);
+
+  const pause = useCallback(() => setIsPaused(true), []);
+  const resume = useCallback(() => setIsPaused(false), []);
+
+  const state: OnboardingOrchestratorState = {
+    isActive,
+    currentStep,
+    currentStepIndex,
+    totalSteps,
+    runtimeState,
+    activeFlow,
+    isComplete,
+    isLoading,
+  };
+
+  const actions: OnboardingOrchestratorActions = {
+    next,
+    prev,
+    skip,
+    complete,
+    updateRuntimeState,
+    refreshFlow,
+    startStep,
+    pause,
+    resume,
+  };
+
+  return { state, actions };
+}
@@ -0,0 +1,184 @@
+import React, { useState } from 'react';
+import { Stack, PasswordInput, Button, Alert, Text } from '@mantine/core';
+import { useTranslation } from 'react-i18next';
+import { SlideConfig } from '@app/types/types';
+import LocalIcon from '@app/components/shared/LocalIcon';
+import { UNIFIED_CIRCLE_CONFIG } from '@app/components/onboarding/slides/unifiedBackgroundConfig';
+import { accountService } from '@app/services/accountService';
+import { alert as showToast } from '@app/components/toast';
+import styles from '@app/components/onboarding/InitialOnboardingModal/InitialOnboardingModal.module.css';
+
+interface FirstLoginSlideProps {
+  username: string;
+  onPasswordChanged: () => void;
+  usingDefaultCredentials?: boolean;
+}
+
+const DEFAULT_PASSWORD = 'stirling';
+
+function FirstLoginForm({ username, onPasswordChanged, usingDefaultCredentials = false }: FirstLoginSlideProps) {
+  const { t } = useTranslation();
+  // If using default credentials, pre-fill with "stirling" - user won't see this field
+  const [currentPassword, setCurrentPassword] = useState(usingDefaultCredentials ? DEFAULT_PASSWORD : '');
+  const [newPassword, setNewPassword] = useState('');
+  const [confirmPassword, setConfirmPassword] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  const handleSubmit = async () => {
+    // Validation
+    if ((!usingDefaultCredentials && !currentPassword) || !newPassword || !confirmPassword) {
+      setError(t('firstLogin.allFieldsRequired', 'All fields are required'));
+      return;
+    }
+
+    if (newPassword !== confirmPassword) {
+      setError(t('firstLogin.passwordsDoNotMatch', 'New passwords do not match'));
+      return;
+    }
+
+    if (newPassword.length < 8) {
+      setError(t('firstLogin.passwordTooShort', 'Password must be at least 8 characters'));
+      return;
+    }
+
+    if (newPassword === currentPassword) {
+      setError(t('firstLogin.passwordMustBeDifferent', 'New password must be different from current password'));
+      return;
+    }
+
+    try {
+      setLoading(true);
+      setError('');
+
+      await accountService.changePasswordOnLogin(currentPassword, newPassword);
+
+      showToast({
+        alertType: 'success',
+        title: t('firstLogin.passwordChangedSuccess', 'Password changed successfully! Please log in again.')
+      });
+
+      // Clear form
+      setCurrentPassword('');
+      setNewPassword('');
+      setConfirmPassword('');
+
+      // Wait a moment for the user to see the success message
+      setTimeout(() => {
+        onPasswordChanged();
+      }, 1500);
+    } catch (err) {
+      console.error('Failed to change password:', err);
+      // Extract error message from axios response if available
+      const axiosError = err as { response?: { data?: { message?: string } } };
+      setError(
+        axiosError.response?.data?.message ||
+        t('firstLogin.passwordChangeFailed', 'Failed to change password. Please check your current password.')
+      );
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className={styles.securitySlideContent}>
+      <div className={styles.securityCard}>
+        <Stack gap="md">
+          <div className={styles.securityAlertRow}>
+            <LocalIcon icon="info-rounded" width={20} height={20} style={{ color: '#3B82F6', flexShrink: 0 }} />
+            <span>
+              {t(
+                'firstLogin.welcomeMessage',
+                'For security reasons, you must change your password on your first login.'
+              )}
+            </span>
+          </div>
+
+          <Text size="sm" fw={500}>
+            {t('firstLogin.loggedInAs', 'Logged in as')}: <strong>{username}</strong>
+          </Text>
+
+          {error && (
+            <Alert
+              icon={<LocalIcon icon="error-rounded" width="1rem" height="1rem" />}
+              color="red"
+              variant="light"
+            >
+              {error}
+            </Alert>
+          )}
+
+          {/* Only show current password field if not using default credentials */}
+          {!usingDefaultCredentials && (
+            <PasswordInput
+              label={t('firstLogin.currentPassword', 'Current Password')}
+              placeholder={t('firstLogin.enterCurrentPassword', 'Enter your current password')}
+              value={currentPassword}
+              onChange={(e) => setCurrentPassword(e.currentTarget.value)}
+              required
+              styles={{
+                input: { height: 44 },
+              }}
+            />
+          )}
+
+          <PasswordInput
+            label={t('firstLogin.newPassword', 'New Password')}
+            placeholder={t('firstLogin.enterNewPassword', 'Enter new password (min 8 characters)')}
+            value={newPassword}
+            onChange={(e) => setNewPassword(e.currentTarget.value)}
+            required
+            styles={{
+              input: { height: 44 },
+            }}
+          />
+
+          <PasswordInput
+            label={t('firstLogin.confirmPassword', 'Confirm New Password')}
+            placeholder={t('firstLogin.reEnterNewPassword', 'Re-enter new password')}
+            value={confirmPassword}
+            onChange={(e) => setConfirmPassword(e.currentTarget.value)}
+            required
+            styles={{
+              input: { height: 44 },
+            }}
+          />
+
+          <Button
+            fullWidth
+            onClick={handleSubmit}
+            loading={loading}
+            disabled={!newPassword || !confirmPassword}
+            size="md"
+            mt="xs"
+          >
+            {t('firstLogin.changePassword', 'Change Password')}
+          </Button>
+        </Stack>
+      </div>
+    </div>
+  );
+}
+
+export default function FirstLoginSlide({
+  username,
+  onPasswordChanged,
+  usingDefaultCredentials = false,
+}: FirstLoginSlideProps): SlideConfig {
+  return {
+    key: 'first-login',
+    title: 'Set Your Password',
+    body: (
+      <FirstLoginForm 
+        username={username} 
+        onPasswordChanged={onPasswordChanged} 
+        usingDefaultCredentials={usingDefaultCredentials}
+      />
+    ),
+    background: {
+      gradientStops: ['#059669', '#0891B2'], // Green to teal - security/trust colors
+      circles: UNIFIED_CIRCLE_CONFIG,
+    },
+  };
+}
+
@@ -1,33 +0,0 @@
-export enum TourStep {
-  ALL_TOOLS,
-  SELECT_CROP_TOOL,
-  TOOL_INTERFACE,
-  FILES_BUTTON,
-  FILE_SOURCES,
-  WORKBENCH,
-  VIEW_SWITCHER,
-  VIEWER,
-  PAGE_EDITOR,
-  ACTIVE_FILES,
-  FILE_CHECKBOX,
-  SELECT_CONTROLS,
-  CROP_SETTINGS,
-  RUN_BUTTON,
-  RESULTS,
-  FILE_REPLACEMENT,
-  PIN_BUTTON,
-  WRAP_UP,
-}
-
-export enum AdminTourStep {
-  WELCOME,
-  CONFIG_BUTTON,
-  SETTINGS_OVERVIEW,
-  TEAMS_AND_USERS,
-  SYSTEM_CUSTOMIZATION,
-  DATABASE_SECTION,
-  CONNECTIONS_SECTION,
-  ADMIN_TOOLS,
-  WRAP_UP,
-}
-
@@ -0,0 +1,79 @@
+/**
+ * useOnboardingDownload Hook
+ * 
+ * Encapsulates OS detection and download URL logic for the desktop install slide.
+ */
+
+import { useState, useEffect, useMemo, useCallback } from 'react';
+import { useOs } from '@app/hooks/useOs';
+import { DOWNLOAD_URLS } from '@app/constants/downloads';
+
+interface OsInfo {
+  label: string;
+  url: string;
+}
+
+interface OsOption {
+  label: string;
+  url: string;
+  value: string;
+}
+
+interface UseOnboardingDownloadResult {
+  osInfo: OsInfo;
+  osOptions: OsOption[];
+  selectedDownloadUrl: string;
+  setSelectedDownloadUrl: (url: string) => void;
+  handleDownloadSelected: () => void;
+}
+
+export function useOnboardingDownload(): UseOnboardingDownloadResult {
+  const osType = useOs();
+  const [selectedDownloadUrl, setSelectedDownloadUrl] = useState<string>('');
+
+  const osInfo = useMemo<OsInfo>(() => {
+    switch (osType) {
+      case 'windows':
+        return { label: 'Windows', url: DOWNLOAD_URLS.WINDOWS };
+      case 'mac-apple':
+        return { label: 'Mac (Apple Silicon)', url: DOWNLOAD_URLS.MAC_APPLE_SILICON };
+      case 'mac-intel':
+        return { label: 'Mac (Intel)', url: DOWNLOAD_URLS.MAC_INTEL };
+      case 'linux-x64':
+      case 'linux-arm64':
+        return { label: 'Linux', url: DOWNLOAD_URLS.LINUX_DOCS };
+      default:
+        return { label: '', url: '' };
+    }
+  }, [osType]);
+
+  const osOptions = useMemo<OsOption[]>(() => [
+    { label: 'Windows', url: DOWNLOAD_URLS.WINDOWS, value: 'windows' },
+    { label: 'Mac (Apple Silicon)', url: DOWNLOAD_URLS.MAC_APPLE_SILICON, value: 'mac-apple' },
+    { label: 'Mac (Intel)', url: DOWNLOAD_URLS.MAC_INTEL, value: 'mac-intel' },
+    { label: 'Linux', url: DOWNLOAD_URLS.LINUX_DOCS, value: 'linux' },
+  ].filter((opt) => opt.url), []);
+
+  // Initialize selected URL from detected OS
+  useEffect(() => {
+    if (!selectedDownloadUrl && osInfo.url) {
+      setSelectedDownloadUrl(osInfo.url);
+    }
+  }, [osInfo.url, selectedDownloadUrl]);
+
+  const handleDownloadSelected = useCallback(() => {
+    const downloadUrl = selectedDownloadUrl || osInfo.url;
+    if (downloadUrl) {
+      window.open(downloadUrl, '_blank', 'noopener');
+    }
+  }, [selectedDownloadUrl, osInfo.url]);
+
+  return {
+    osInfo,
+    osOptions,
+    selectedDownloadUrl,
+    setSelectedDownloadUrl,
+    handleDownloadSelected,
+  };
+}
+
@@ -0,0 +1,74 @@
+import { useEffect, useCallback, useState } from 'react';
+import {
+  SERVER_LICENSE_REQUEST_EVENT,
+  START_TOUR_EVENT,
+  type ServerLicenseRequestPayload,
+  type TourType,
+  type StartTourPayload,
+} from '@app/constants/events';
+import type { OnboardingRuntimeState } from '@app/components/onboarding/orchestrator/onboardingConfig';
+
+export function useServerLicenseRequest(): {
+  showLicenseSlide: boolean;
+  licenseNotice: OnboardingRuntimeState['licenseNotice'] | null;
+  closeLicenseSlide: () => void;
+} {
+  const [showLicenseSlide, setShowLicenseSlide] = useState(false);
+  const [licenseNotice, setLicenseNotice] = useState<OnboardingRuntimeState['licenseNotice'] | null>(null);
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handleLicenseRequest = (event: Event) => {
+      const { detail } = event as CustomEvent<ServerLicenseRequestPayload>;
+      
+      if (detail?.licenseNotice) {
+        setLicenseNotice({
+          totalUsers: detail.licenseNotice.totalUsers ?? null,
+          freeTierLimit: detail.licenseNotice.freeTierLimit ?? 5,
+          isOverLimit: detail.licenseNotice.isOverLimit ?? false,
+          requiresLicense: true,
+        });
+      }
+      
+      setShowLicenseSlide(true);
+    };
+
+    window.addEventListener(SERVER_LICENSE_REQUEST_EVENT, handleLicenseRequest);
+    return () => window.removeEventListener(SERVER_LICENSE_REQUEST_EVENT, handleLicenseRequest);
+  }, []);
+
+  const closeLicenseSlide = useCallback(() => {
+    setShowLicenseSlide(false);
+  }, []);
+
+  return { showLicenseSlide, licenseNotice, closeLicenseSlide };
+}
+
+export function useTourRequest(): {
+  tourRequested: boolean;
+  requestedTourType: TourType;
+  clearTourRequest: () => void;
+} {
+  const [tourRequested, setTourRequested] = useState(false);
+  const [requestedTourType, setRequestedTourType] = useState<TourType>('tools');
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const handleTourRequest = (event: Event) => {
+      const { detail } = event as CustomEvent<StartTourPayload>;
+      setRequestedTourType(detail?.tourType ?? 'tools');
+      setTourRequested(true);
+    };
+
+    window.addEventListener(START_TOUR_EVENT, handleTourRequest);
+    return () => window.removeEventListener(START_TOUR_EVENT, handleTourRequest);
+  }, []);
+
+  const clearTourRequest = useCallback(() => {
+    setTourRequested(false);
+  }, []);
+
+  return { tourRequested, requestedTourType, clearTourRequest };
+}
@@ -1,6 +1,26 @@
 import type { StepType } from '@reactour/tour';
 import type { TFunction } from 'i18next';
-import { TourStep } from '@app/components/onboarding/tourSteps';
+
+export enum TourStep {
+  ALL_TOOLS,
+  SELECT_CROP_TOOL,
+  TOOL_INTERFACE,
+  FILES_BUTTON,
+  FILE_SOURCES,
+  WORKBENCH,
+  VIEW_SWITCHER,
+  VIEWER,
+  PAGE_EDITOR,
+  ACTIVE_FILES,
+  FILE_CHECKBOX,
+  SELECT_CONTROLS,
+  CROP_SETTINGS,
+  RUN_BUTTON,
+  RESULTS,
+  FILE_REPLACEMENT,
+  PIN_BUTTON,
+  WRAP_UP,
+}

 interface UserStepActions {
  saveWorkbenchState: () => void;
@@ -7,7 +7,7 @@ import { NavKey, VALID_NAV_KEYS } from '@app/components/shared/config/types';
 import { useAppConfig } from '@app/contexts/AppConfigContext';
 import '@app/components/shared/AppConfigModal.css';
 import { useIsMobile } from '@app/hooks/useIsMobile';
-import { Z_INDEX_OVER_FULLSCREEN_SURFACE, Z_INDEX_OVER_CONFIG_MODAL } from '@app/styles/zIndex';
+import { Z_INDEX_CONFIG_MODAL, Z_INDEX_OVER_CONFIG_MODAL } from '@app/styles/zIndex';
 import { useLicenseAlert } from '@app/hooks/useLicenseAlert';
 import { UnsavedChangesProvider, useUnsavedChanges } from '@app/contexts/UnsavedChangesContext';

@@ -122,7 +122,7 @@ const AppConfigModalInner: React.FC<AppConfigModalProps> = ({ opened, onClose })
      centered
      radius="lg"
      withCloseButton={false}
-      zIndex={Z_INDEX_OVER_FULLSCREEN_SURFACE}
+      zIndex={Z_INDEX_CONFIG_MODAL}
      overlayProps={{ opacity: 0.35, blur: 2 }}
      padding={0}
      fullScreen={isMobile}
@@ -130,11 +130,6 @@ export const InfoBanner: React.FC<InfoBannerProps> = ({
              onClick={onButtonClick}
              loading={loading}
              leftSection={<LocalIcon icon={buttonIcon} width="0.9rem" height="0.9rem" />}
-              styles={{
-                label: {
-                  color: textColor ?? toneStyle.text,
-                },
-              }}
            >
              {buttonText}
            </Button>
@@ -15,8 +15,8 @@ import AllToolsNavButton from '@app/components/shared/AllToolsNavButton';
 import ActiveToolButton from "@app/components/shared/quickAccessBar/ActiveToolButton";
 import AppConfigModal from '@app/components/shared/AppConfigModal';
 import { useAppConfig } from '@app/contexts/AppConfigContext';
-import { useOnboarding } from '@app/contexts/OnboardingContext';
 import { useLicenseAlert } from "@app/hooks/useLicenseAlert";
+import { requestStartTour } from '@app/constants/events';

 import {
  isNavButtonActive,
@@ -34,7 +34,6 @@ const QuickAccessBar = forwardRef<HTMLDivElement>((_, ref) => {
  const { handleReaderToggle, handleToolSelect, selectedToolKey, leftPanelView, toolRegistry, readerMode, resetTool } = useToolWorkflow();
  const { getToolNavigation } = useSidebarNavigation();
  const { config } = useAppConfig();
-  const { startTour } = useOnboarding();
  const licenseAlert = useLicenseAlert();
  const [configModalOpen, setConfigModalOpen] = useState(false);
  const [activeButton, setActiveButton] = useState<string>('tools');
@@ -269,7 +268,7 @@ const QuickAccessBar = forwardRef<HTMLDivElement>((_, ref) => {
                    <div
                      key={buttonConfig.id}
                      data-tour="help-button"
-                      onClick={() => startTour('tools')}
+                      onClick={() => requestStartTour('tools')}
                    >
                      {renderNavButton(buttonConfig, index)}
                    </div>
@@ -286,7 +285,7 @@ const QuickAccessBar = forwardRef<HTMLDivElement>((_, ref) => {
                      <Menu.Dropdown>
                        <Menu.Item
                          leftSection={<LocalIcon icon="view-carousel-rounded" width="1.25rem" height="1.25rem" />}
-                          onClick={() => startTour('tools')}
+                          onClick={() => requestStartTour('tools')}
                        >
                          <div>
                            <div style={{ fontWeight: 500 }}>
@@ -299,7 +298,7 @@ const QuickAccessBar = forwardRef<HTMLDivElement>((_, ref) => {
                        </Menu.Item>
                        <Menu.Item
                          leftSection={<LocalIcon icon="admin-panel-settings-rounded" width="1.25rem" height="1.25rem" />}
-                          onClick={() => startTour('admin')}
+                          onClick={() => requestStartTour('admin')}
                        >
                          <div>
                            <div style={{ fontWeight: 500 }}>
@@ -3,65 +3,39 @@ import { Badge, Button, Card, Group, Modal, Stack, Text } from '@mantine/core';
 import { useTranslation } from 'react-i18next';
 import { useToolWorkflow } from '@app/contexts/ToolWorkflowContext';
 import { usePreferences } from '@app/contexts/PreferencesContext';
-import { useOnboarding } from '@app/contexts/OnboardingContext';
 import '@app/components/tools/ToolPanelModePrompt.css';
 import { type ToolPanelMode } from '@app/constants/toolPanel';
-import { useAppConfig } from '@app/contexts/AppConfigContext';

 interface ToolPanelModePromptProps {
  onComplete?: () => void;
+  /** If true, the modal will be forced open (used by orchestrator) */
+  forceOpen?: boolean;
 }

-const ToolPanelModePrompt = ({ onComplete }: ToolPanelModePromptProps = {}) => {
+/**
+ * ToolPanelModePrompt - Lets users choose between sidebar and fullscreen tool modes
+ * 
+ * The orchestrator controls this via forceOpen prop. When shown standalone (legacy),
+ * it uses internal state based on preferences.
+ */
+const ToolPanelModePrompt = ({ onComplete, forceOpen }: ToolPanelModePromptProps = {}) => {
  const { t } = useTranslation();
  const { toolPanelMode, setToolPanelMode } = useToolWorkflow();
  const { preferences, updatePreference } = usePreferences();
-  const {
-    startTour,
-    startAfterToolModeSelection,
-    setStartAfterToolModeSelection,
-    pendingTourRequest,
-  } = useOnboarding();
-  const [opened, setOpened] = useState(false);
-  const { config } = useAppConfig();
-  const isAdmin = !!config?.isAdmin;
+  const [internalOpened, setInternalOpened] = useState(false);

-  // Only show after the new 3-slide onboarding has been completed
+  // Only show after the intro onboarding has been completed (legacy standalone mode)
  const shouldShowPrompt = !preferences.toolPanelModePromptSeen && preferences.hasSeenIntroOnboarding;

  useEffect(() => {
-    if (shouldShowPrompt) {
-      setOpened(true);
+    if (shouldShowPrompt && forceOpen === undefined) {
+      setInternalOpened(true);
    }
-  }, [shouldShowPrompt]);
+  }, [shouldShowPrompt, forceOpen]);

-  const resolveRequestedTourType = (): 'admin' | 'tools' => {
-    if (pendingTourRequest?.type) {
-      return pendingTourRequest.type;
-    }
-    if (pendingTourRequest?.metadata && 'selfReportedAdmin' in pendingTourRequest.metadata) {
-      return pendingTourRequest.metadata.selfReportedAdmin ? 'admin' : 'tools';
-    }
-    return isAdmin ? 'admin' : 'tools';
-  };
-
-  const resumeDeferredTour = (context?: { selection?: ToolPanelMode; dismissed?: boolean }) => {
-    if (!startAfterToolModeSelection) {
-      return;
-    }
-    setStartAfterToolModeSelection(false);
-    const targetType = resolveRequestedTourType();
-    startTour(targetType, {
-      skipToolPromptRequirement: true,
-      source: 'tool-panel-mode-prompt',
-      metadata: {
-        ...pendingTourRequest?.metadata,
-        resumedFromToolPrompt: true,
-        ...(context?.selection ? { selection: context.selection } : {}),
-        ...(context?.dismissed ? { dismissed: true } : {}),
-      },
-    });
-  };
+  // If forceOpen is provided, use it; otherwise use internal state
+  const opened = forceOpen ?? internalOpened;
+  const setOpened = forceOpen !== undefined ? () => {} : setInternalOpened;

  const handleSelect = (mode: ToolPanelMode) => {
    setToolPanelMode(mode);
@@ -69,8 +43,6 @@ const ToolPanelModePrompt = ({ onComplete }: ToolPanelModePromptProps = {}) => {
    updatePreference('toolPanelModePromptSeen', true);
    updatePreference('hasSelectedToolPanelMode', true);
    setOpened(false);
-
-    resumeDeferredTour({ selection: mode });
    onComplete?.();
  };

@@ -83,7 +55,6 @@ const ToolPanelModePrompt = ({ onComplete }: ToolPanelModePromptProps = {}) => {
    updatePreference('hasSelectedToolPanelMode', true);
    updatePreference('toolPanelModePromptSeen', true);
    setOpened(false);
-    resumeDeferredTour({ dismissed: true });
    onComplete?.();
  };

@@ -33,7 +33,7 @@ import MergeTypeIcon from '@mui/icons-material/MergeType';
 import CallSplitIcon from '@mui/icons-material/CallSplit';
 import MoreVertIcon from '@mui/icons-material/MoreVert';
 import { Rnd } from 'react-rnd';
-import NavigationWarningModal from '@core/components/shared/NavigationWarningModal';
+import NavigationWarningModal from '@app/components/shared/NavigationWarningModal';

 import {
  PdfTextEditorViewData,
@@ -2147,14 +2147,20 @@ const selectionToolbarPosition = useMemo(() => {
                      // Determine text wrapping behavior based on whether text has been changed
                      const hasChanges = changed;
                      const widthExtended = resolvedWidth - baseWidth > 0.5;
-                      const enableWrap = isParagraphLayout || widthExtended || isEditing || hasChanges;
+                      // Only enable wrapping if:
+                      // 1. It's paragraph layout (multi-line groups should wrap)
+                      // 2. Width was manually extended (user explicitly made space for wrapping)
+                      // 3. Has changes AND was already wrapping (preserve existing wrap state)
+                      // DO NOT enable wrapping just because isEditing - text should only wrap when it actually overflows
+                      const wasWrapping = isParagraphLayout || widthExtended;
+                      const enableWrap = wasWrapping || (hasChanges && wasWrapping);
                      const whiteSpace = enableWrap ? 'pre-wrap' : 'pre';
                      const wordBreak = enableWrap ? 'break-word' : 'normal';
                      const overflowWrap = enableWrap ? 'break-word' : 'normal';

                      // For paragraph mode, allow height to grow to accommodate lines without wrapping
                      // For single-line mode, maintain fixed height based on PDF bounds
-                      const useFlexibleHeight = isEditing || enableWrap || (isParagraphLayout && lineCount > 1);
+                      const useFlexibleHeight = enableWrap || (isParagraphLayout && lineCount > 1);

                      // The renderGroupContainer wrapper adds 4px horizontal padding (2px left + 2px right)
                      // We need to add this to the container width to compensate, so the inner content
@@ -20,6 +20,7 @@ import { ThumbnailPluginPackage } from '@embedpdf/plugin-thumbnail/react';
 import { RotatePluginPackage, Rotate } from '@embedpdf/plugin-rotate/react';
 import { ExportPluginPackage } from '@embedpdf/plugin-export/react';
 import { BookmarkPluginPackage } from '@embedpdf/plugin-bookmark';
+import { PrintPluginPackage } from '@embedpdf/plugin-print/react';

 // Import annotation plugins
 import { HistoryPluginPackage } from '@embedpdf/plugin-history/react';
@@ -41,6 +42,7 @@ import { HistoryAPIBridge } from '@app/components/viewer/HistoryAPIBridge';
 import type { SignatureAPI, HistoryAPI } from '@app/components/viewer/viewerTypes';
 import { ExportAPIBridge } from '@app/components/viewer/ExportAPIBridge';
 import { BookmarkAPIBridge } from '@app/components/viewer/BookmarkAPIBridge';
+import { PrintAPIBridge } from '@app/components/viewer/PrintAPIBridge';
 import { isPdfFile } from '@app/utils/fileUtils';
 import { useTranslation } from 'react-i18next';
 import { LinkLayer } from '@app/components/viewer/LinkLayer';
@@ -156,6 +158,9 @@ export function LocalEmbedPDF({ file, url, enableAnnotations = false, onSignatur
      createPluginRegistration(ExportPluginPackage, {
        defaultFileName: 'document.pdf',
      }),
+
+      // Register print plugin for printing PDFs
+      createPluginRegistration(PrintPluginPackage),
    ];
  }, [pdfUrl]);

@@ -301,6 +306,7 @@ export function LocalEmbedPDF({ file, url, enableAnnotations = false, onSignatur
        {enableAnnotations && <HistoryAPIBridge ref={historyApiRef} />}
        <ExportAPIBridge />
        <BookmarkAPIBridge />
+        <PrintAPIBridge />
        <GlobalPointerProvider>
          <Viewport
            style={{
@@ -0,0 +1,25 @@
+import { useEffect } from 'react';
+import { usePrintCapability } from '@embedpdf/plugin-print/react';
+import { useViewer } from '@app/contexts/ViewerContext';
+
+/**
+ * Component that runs inside EmbedPDF context and exposes print API to ViewerContext
+ */
+export function PrintAPIBridge() {
+  const { provides: print } = usePrintCapability();
+  const { registerBridge } = useViewer();
+
+  useEffect(() => {
+    if (print) {
+      // Register this bridge with ViewerContext
+      registerBridge('print', {
+        state: {},
+        api: {
+          print: () => print.print(),
+        }
+      });
+    }
+  }, [print, registerBridge]);
+
+  return null;
+}
@@ -24,6 +24,7 @@ export function useViewerRightRailButtons() {
  const rotateRightLabel = t('rightRail.rotateRight', 'Rotate Right');
  const sidebarLabel = t('rightRail.toggleSidebar', 'Toggle Sidebar');
  const bookmarkLabel = t('rightRail.toggleBookmarks', 'Toggle Bookmarks');
+  const printLabel = t('rightRail.print', 'Print PDF');

  const viewerButtons = useMemo<RightRailButtonWithAction[]>(() => {
    return [
@@ -127,6 +128,17 @@ export function useViewerRightRailButtons() {
          viewer.toggleBookmarkSidebar();
        }
      },
+      {
+        id: 'viewer-print',
+        icon: <LocalIcon icon="print" width="1.5rem" height="1.5rem" />,
+        tooltip: printLabel,
+        ariaLabel: printLabel,
+        section: 'top' as const,
+        order: 56,
+        onClick: () => {
+          viewer.printActions.print();
+        }
+      },
      {
        id: 'viewer-annotation-controls',
        section: 'top' as const,
@@ -136,7 +148,7 @@ export function useViewerRightRailButtons() {
        )
      }
    ];
-  }, [t, i18n.language, viewer, isPanning, searchLabel, panLabel, rotateLeftLabel, rotateRightLabel, sidebarLabel, bookmarkLabel, tooltipPosition]);
+  }, [t, i18n.language, viewer, isPanning, searchLabel, panLabel, rotateLeftLabel, rotateRightLabel, sidebarLabel, bookmarkLabel, printLabel, tooltipPosition]);

  useRightRailButtons(viewerButtons);
 }
@@ -1,10 +1,10 @@
 import type { LicenseNotice } from '@app/types/types';

-export const ONBOARDING_SESSION_BLOCK_KEY = 'stirling-onboarding-session-active';
-export const ONBOARDING_SESSION_EVENT = 'stirling:onboarding-session-started';
 export const SERVER_LICENSE_REQUEST_EVENT = 'stirling:server-license-requested';
 export const UPGRADE_BANNER_TEST_EVENT = 'stirling:upgrade-banner-test';
 export const UPGRADE_BANNER_ALERT_EVENT = 'stirling:upgrade-banner-alert';
+export const START_TOUR_EVENT = 'stirling:start-tour';
+export const TOUR_STATE_EVENT = 'stirling:tour-state';

 export interface ServerLicenseRequestPayload {
  licenseNotice?: Partial<LicenseNotice>;
@@ -25,3 +25,29 @@ export interface UpgradeBannerAlertPayload {
  freeTierLimit?: number;
 }

+export type TourType = 'admin' | 'tools';
+
+export interface StartTourPayload {
+  tourType: TourType;
+}
+
+export interface TourStatePayload {
+  isOpen: boolean;
+}
+
+/** Helper to dispatch the start tour event */
+export function requestStartTour(tourType: TourType): void {
+  if (typeof window === 'undefined') return;
+  window.dispatchEvent(
+    new CustomEvent<StartTourPayload>(START_TOUR_EVENT, { detail: { tourType } })
+  );
+}
+
+/** Helper to dispatch tour state changes (for hiding cookie consent during tour) */
+export function dispatchTourState(isOpen: boolean): void {
+  if (typeof window === 'undefined') return;
+  window.dispatchEvent(
+    new CustomEvent<TourStatePayload>(TOUR_STATE_EVENT, { detail: { isOpen } })
+  );
+}
+
@@ -0,0 +1,25 @@
+/**
+ * Route constants used across the application
+ */
+
+/**
+ * Routes where onboarding, cookie consent, and upgrade banners should not appear.
+ * These are authentication-related pages where users are not yet logged in or
+ * the main app chrome is not displayed.
+ */
+export const AUTH_ROUTES = [
+  '/login',
+  '/signup',
+  '/auth',
+  '/invite',
+  '/forgot-password',
+  '/reset-password',
+];
+
+/**
+ * Check if a pathname matches any auth route
+ */
+export function isAuthRoute(pathname: string): boolean {
+  return AUTH_ROUTES.some((route) => pathname.startsWith(route));
+}
+
@@ -1,159 +0,0 @@
-import React, { createContext, useContext, useState, useCallback } from 'react';
-import { usePreferences } from '@app/contexts/PreferencesContext';
-
-export type TourType = 'tools' | 'admin';
-
-export interface StartTourOptions {
-  source?: string;
-  skipToolPromptRequirement?: boolean;
-  metadata?: Record<string, unknown>;
-}
-
-interface PendingTourRequest {
-  type: TourType;
-  source?: string;
-  metadata?: Record<string, unknown>;
-  requestedAt: number;
-}
-
-interface OnboardingContextValue {
-  isOpen: boolean;
-  currentStep: number;
-  tourType: TourType;
-  setCurrentStep: (step: number) => void;
-  startTour: (type?: TourType, options?: StartTourOptions) => void;
-  closeTour: () => void;
-  completeTour: () => void;
-  resetTour: (type?: TourType) => void;
-  startAfterToolModeSelection: boolean;
-  setStartAfterToolModeSelection: (value: boolean) => void;
-  pendingTourRequest: PendingTourRequest | null;
-  clearPendingTourRequest: () => void;
-}
-
-const OnboardingContext = createContext<OnboardingContextValue | undefined>(undefined);
-
-export const OnboardingProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
-  const { preferences, updatePreference } = usePreferences();
-  const [isOpen, setIsOpen] = useState(false);
-  const [currentStep, setCurrentStep] = useState(0);
-  const [tourType, setTourType] = useState<TourType>('tools');
-  const [startAfterToolModeSelection, setStartAfterToolModeSelection] = useState(false);
-  const [pendingTourRequest, setPendingTourRequest] = useState<PendingTourRequest | null>(null);
-
-  const openTour = useCallback((type: TourType = 'tools') => {
-    setTourType(type);
-    setCurrentStep(0);
-    setIsOpen(true);
-  }, []);
-
-  const startTour = useCallback(
-    (type: TourType = 'tools', options?: StartTourOptions) => {
-      const requestedType = type ?? 'tools';
-      const source = options?.source ?? 'unspecified';
-      const metadata = options?.metadata;
-      const skipToolPromptRequirement = options?.skipToolPromptRequirement ?? false;
-      const toolPromptSeen = preferences.toolPanelModePromptSeen;
-      const hasSelectedToolPanelMode = preferences.hasSelectedToolPanelMode;
-      const hasToolPreference = toolPromptSeen || hasSelectedToolPanelMode;
-      const shouldDefer = !skipToolPromptRequirement && !hasToolPreference;
-
-      console.log('[onboarding] startTour invoked', {
-        requestedType,
-        source,
-        toolPromptSeen,
-        hasSelectedToolPanelMode,
-        shouldDefer,
-        hasPendingTourRequest: !!pendingTourRequest,
-        metadata,
-      });
-
-      if (shouldDefer) {
-        setPendingTourRequest({
-          type: requestedType,
-          source,
-          metadata,
-          requestedAt: Date.now(),
-        });
-        setStartAfterToolModeSelection(true);
-        console.log('[onboarding] deferring tour launch until tool panel mode selection completes', {
-          requestedType,
-          source,
-        });
-        return;
-      }
-
-      if (pendingTourRequest) {
-        console.log('[onboarding] clearing previous pending tour request before starting new tour', {
-          previousRequest: pendingTourRequest,
-          newType: requestedType,
-          source,
-        });
-      }
-
-      setPendingTourRequest(null);
-      setStartAfterToolModeSelection(false);
-      console.log('[onboarding] starting tour', {
-        requestedType,
-        source,
-      });
-      openTour(requestedType);
-    },
-    [openTour, pendingTourRequest, preferences.toolPanelModePromptSeen, preferences.hasSelectedToolPanelMode],
-  );
-
-  const closeTour = useCallback(() => {
-    setIsOpen(false);
-  }, []);
-
-  const completeTour = useCallback(() => {
-    setIsOpen(false);
-    updatePreference('hasCompletedOnboarding', true);
-  }, [updatePreference]);
-
-  const resetTour = useCallback((type: TourType = 'tools') => {
-    updatePreference('hasCompletedOnboarding', false);
-    setTourType(type);
-    setCurrentStep(0);
-    setIsOpen(true);
-  }, [updatePreference]);
-
-  const clearPendingTourRequest = useCallback(() => {
-    if (pendingTourRequest) {
-      console.log('[onboarding] clearing pending tour request manually', {
-        pendingTourRequest,
-      });
-    }
-    setPendingTourRequest(null);
-    setStartAfterToolModeSelection(false);
-  }, [pendingTourRequest]);
-
-  return (
-    <OnboardingContext.Provider
-      value={{
-        isOpen,
-        currentStep,
-        tourType,
-        setCurrentStep,
-        startTour,
-        closeTour,
-        completeTour,
-        resetTour,
-        startAfterToolModeSelection,
-        setStartAfterToolModeSelection,
-        pendingTourRequest,
-        clearPendingTourRequest,
-      }}
-    >
-      {children}
-    </OnboardingContext.Provider>
-  );
-};
-
-export const useOnboarding = (): OnboardingContextValue => {
-  const context = useContext(OnboardingContext);
-  if (!context) {
-    throw new Error('useOnboarding must be used within an OnboardingProvider');
-  }
-  return context;
-};
@@ -18,6 +18,7 @@ import {
  SearchActions,
  ExportActions,
  BookmarkActions,
+  PrintActions,
 } from '@app/contexts/viewer/viewerActions';
 import {
  BridgeRef,
@@ -125,6 +126,7 @@ interface ViewerContextType {
  searchActions: SearchActions;
  exportActions: ExportActions;
  bookmarkActions: BookmarkActions;
+  printActions: PrintActions;

  // Bridge registration - internal use by bridges  
  registerBridge: <K extends BridgeKey>(
@@ -277,6 +279,7 @@ export const ViewerProvider: React.FC<ViewerProviderProps> = ({ children }) => {
    searchActions,
    exportActions,
    bookmarkActions,
+    printActions,
  } = createViewerActions({
    registry: bridgeRefs,
    getScrollState,
@@ -333,6 +336,7 @@ export const ViewerProvider: React.FC<ViewerProviderProps> = ({ children }) => {
    searchActions,
    exportActions,
    bookmarkActions,
+    printActions,

    // Bridge registration
    registerBridge,
@@ -65,6 +65,10 @@ export interface BookmarkActions {
  setLocalBookmarks: (bookmarks: PdfBookmarkObject[] | null, error?: string | null) => void;
 }

+export interface PrintActions {
+  print: () => void;
+}
+
 export interface ViewerActionsBundle {
  scrollActions: ScrollActions;
  zoomActions: ZoomActions;
@@ -75,6 +79,7 @@ export interface ViewerActionsBundle {
  searchActions: SearchActions;
  exportActions: ExportActions;
  bookmarkActions: BookmarkActions;
+  printActions: PrintActions;
 }

 interface ViewerActionDependencies {
@@ -332,5 +337,13 @@ export function createViewerActions({
        api?.setLocalBookmarks?.(bookmarks ?? null, error);
      },
    },
+    printActions: {
+      print: () => {
+        const api = registry.current.print?.api;
+        if (api?.print) {
+          api.print();
+        }
+      },
+    },
  };
 }
@@ -49,6 +49,10 @@ export interface SearchAPIWrapper {
  goToResult: (index: number) => void;
 }

+export interface PrintAPIWrapper {
+  print: () => void;
+}
+
 export interface ThumbnailAPIWrapper {
  renderThumb: (pageIndex: number, scale: number) => {
    toPromise: () => Promise<Blob>;
@@ -132,6 +136,7 @@ export interface BridgeStateMap {
  thumbnail: unknown;
  export: ExportState;
  bookmark: BookmarkState;
+  print: unknown;
 }

 export interface BridgeApiMap {
@@ -145,6 +150,7 @@ export interface BridgeApiMap {
  thumbnail: ThumbnailAPIWrapper;
  export: ExportAPIWrapper;
  bookmark: BookmarkAPIWrapper;
+  print: PrintAPIWrapper;
 }

 export type BridgeKey = keyof BridgeStateMap;
@@ -164,6 +170,7 @@ export const createBridgeRegistry = (): ViewerBridgeRegistry => ({
  thumbnail: null,
  export: null,
  bookmark: null,
+  print: null,
 });

 export function registerBridge<K extends BridgeKey>(
@@ -43,6 +43,7 @@ import CertSign from "@app/tools/CertSign";
 import BookletImposition from "@app/tools/BookletImposition";
 import Flatten from "@app/tools/Flatten";
 import Rotate from "@app/tools/Rotate";
+import PdfTextEditor from "@app/tools/pdfTextEditor/PdfTextEditor";
 import ChangeMetadata from "@app/tools/ChangeMetadata";
 import Crop from "@app/tools/Crop";
 import Sign from "@app/tools/Sign";
@@ -890,6 +891,23 @@ export function useTranslatedToolCatalog(): TranslatedToolCatalog {
        automationSettings: RedactSingleStepSettings,
        synonyms: getSynonyms(t, "redact")
      },
+      pdfTextEditor: {
+        icon: <LocalIcon icon="edit-square-outline-rounded" width="1.5rem" height="1.5rem" />,
+        name: t("home.pdfTextEditor.title", "PDF Text Editor"),
+        component: PdfTextEditor,
+        description: t(
+          "home.pdfTextEditor.desc",
+          "Review and edit text and images in PDFs with grouped text editing and PDF regeneration"
+        ),
+        categoryId: ToolCategoryId.RECOMMENDED_TOOLS,
+        subcategoryId: SubcategoryId.GENERAL,
+        maxFiles: 1,
+        endpoints: ["text-editor-pdf"],
+        synonyms: getSynonyms(t, "pdfTextEditor"),
+        supportsAutomate: false,
+        automationSettings: null,
+        versionStatus: "alpha",
+      },
    };

    const regularTools = {} as RegularToolRegistry;
@@ -2,7 +2,7 @@ import { useEffect, useState, useCallback } from 'react';
 import { useTranslation } from 'react-i18next';
 import { BASE_PATH } from '@app/constants/app';
 import { useAppConfig } from '@app/contexts/AppConfigContext';
-import { useOnboarding } from '@app/contexts/OnboardingContext';
+import { TOUR_STATE_EVENT, type TourStatePayload } from '@app/constants/events';

 declare global {
  interface Window {
@@ -28,16 +28,11 @@ export const useCookieConsent = ({
 }: CookieConsentConfig = {}) => {
  const { t } = useTranslation();
  const { config } = useAppConfig();
-  const { isOpen: tourIsOpen } = useOnboarding();
  const [isInitialized, setIsInitialized] = useState(false);

  useEffect(() => {
-    if (!analyticsEnabled) {
-      console.log('Cookie consent not enabled - analyticsEnabled is false');
-      return;
-    }
+    if (!analyticsEnabled) return;

-    // Load the cookie consent CSS files first (always needed)
    const mainCSS = document.createElement('link');
    mainCSS.rel = 'stylesheet';
    mainCSS.href = `${BASE_PATH}css/cookieconsent.css`;
@@ -52,26 +47,19 @@ export const useCookieConsent = ({
      document.head.appendChild(customCSS);
    }

-    // Prevent double initialization
    if (window.CookieConsent) {
+      if (forceLightMode) {
+        document.documentElement.classList.remove('cc--darkmode');
+      }
      setIsInitialized(true);
-      // Force show the modal if it exists but isn't visible
-      setTimeout(() => {
-        window.CookieConsent?.show();
-      }, 100);
      return;
    }

-    // Load the cookie consent library
    const script = document.createElement('script');
    script.src = `${BASE_PATH}js/thirdParty/cookieconsent.umd.js`;
    script.onload = () => {
-      // Small delay to ensure DOM is ready
      setTimeout(() => {
-
-        // Detect current theme and set appropriate mode
        const detectTheme = () => {
-          // If forceLightMode is enabled, always use light mode
          if (forceLightMode) {
            document.documentElement.classList.remove('cc--darkmode');
            return false;
@@ -82,7 +70,6 @@ export const useCookieConsent = ({
          const hasDarkClass = document.documentElement.classList.contains('dark');
          const systemPrefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;

-          // Priority: Mantine attribute > CSS classes > system preference
          let isDarkMode = false;

          if (mantineScheme) {
@@ -95,24 +82,17 @@ export const useCookieConsent = ({
            isDarkMode = systemPrefersDark;
          }

-          // Always explicitly set or remove the class
          document.documentElement.classList.toggle('cc--darkmode', isDarkMode);
-
          return isDarkMode;
        };

-        // Initial theme detection with slight delay to ensure DOM is ready
-        setTimeout(() => {
-          detectTheme();
-        }, 50);
+        setTimeout(() => detectTheme(), 50);

-        // Check if CookieConsent is available
        if (!window.CookieConsent) {
          console.error('CookieConsent is not available on window object');
          return;
        }

-        // Listen for theme changes (but not if forceLightMode is enabled)
        let themeObserver: MutationObserver | null = null;
        if (!forceLightMode) {
          themeObserver = new MutationObserver((mutations) => {
@@ -131,8 +111,6 @@ export const useCookieConsent = ({
          });
        }

-
-        // Initialize cookie consent with full configuration
        try {
          window.CookieConsent.run({
            autoShow: true,
@@ -160,15 +138,11 @@ export const useCookieConsent = ({
                  ...(config?.enablePosthog !== false && {
                    posthog: {
                      label: t('cookieBanner.services.posthog', 'PostHog Analytics'),
-                      onAccept: () => console.log('PostHog service accepted'),
-                      onReject: () => console.log('PostHog service rejected')
                    }
                  }),
                  ...(config?.enableScarf !== false && {
                    scarf: {
                      label: t('cookieBanner.services.scarf', 'Scarf Pixel'),
-                      onAccept: () => console.log('Scarf service accepted'),
-                      onReject: () => console.log('Scarf service rejected')
                    }
                  })
                }
@@ -224,16 +198,11 @@ export const useCookieConsent = ({
            }
          });

-          // Force show after initialization
-          setTimeout(() => {
-            window.CookieConsent?.show();
-          }, 200);
-
        } catch (error) {
          console.error('Error initializing CookieConsent:', error);
        }
-      setIsInitialized(true);
-      }, 100); // Small delay to ensure DOM is ready
+        setIsInitialized(true);
+      }, 100);
    };

    script.onerror = () => {
@@ -243,7 +212,6 @@ export const useCookieConsent = ({
    document.head.appendChild(script);

    return () => {
-      // Cleanup script and CSS when component unmounts
      if (document.head.contains(script)) {
        document.head.removeChild(script);
      }
@@ -254,9 +222,8 @@ export const useCookieConsent = ({
        document.head.removeChild(customCSS);
      }
    };
-  }, [analyticsEnabled, config?.enablePosthog, config?.enableScarf, t]);
+  }, [analyticsEnabled, config?.enablePosthog, config?.enableScarf, t, forceLightMode]);

-  // Update theme when forceLightMode changes
  useEffect(() => {
    if (!isInitialized) return;

@@ -286,10 +253,8 @@ export const useCookieConsent = ({
      return isDarkMode;
    };

-    // Update theme immediately
    detectTheme();

-    // Set up or remove theme observer based on forceLightMode
    let themeObserver: MutationObserver | null = null;
    if (!forceLightMode) {
      themeObserver = new MutationObserver((mutations) => {
@@ -315,23 +280,23 @@ export const useCookieConsent = ({
    };
  }, [forceLightMode, isInitialized]);

-  // Hide cookie banner when tour is active
  useEffect(() => {
-    if (!isInitialized || !window.CookieConsent) {
-      return;
-    }
+    if (!isInitialized || !window.CookieConsent) return;

-    if (tourIsOpen) {
-      window.CookieConsent.hide();
-    } else {
-      // Only show if user hasn't made a choice yet
-      const consentCookie = window.CookieConsent.getCookie?.();
-      const hasConsented = consentCookie && Object.keys(consentCookie).length > 0;
-      if (!hasConsented) {
-        window.CookieConsent.show();
+    const handleTourState = (event: Event) => {
+      const { detail } = event as CustomEvent<TourStatePayload>;
+      if (detail?.isOpen) {
+        window.CookieConsent?.hide();
+      } else {
+        const consentCookie = window.CookieConsent?.getCookie?.();
+        const hasConsented = consentCookie && Object.keys(consentCookie).length > 0;
+        if (!hasConsented) window.CookieConsent?.show();
      }
-    }
-  }, [tourIsOpen, isInitialized]);
+    };
+
+    window.addEventListener(TOUR_STATE_EVENT, handleTourState);
+    return () => window.removeEventListener(TOUR_STATE_EVENT, handleTourState);
+  }, [isInitialized]);

  const showCookieConsent = useCallback(() => {
    if (isInitialized && window.CookieConsent) {
@@ -22,7 +22,6 @@ import FileManager from "@app/components/FileManager";
 import LocalIcon from "@app/components/shared/LocalIcon";
 import { useFilesModalContext } from "@app/contexts/FilesModalContext";
 import AppConfigModal from "@app/components/shared/AppConfigModal";
-import AdminAnalyticsChoiceModal from "@app/components/shared/AdminAnalyticsChoiceModal";

 import "@app/pages/HomePage.css";

@@ -53,20 +52,12 @@ export default function HomePage() {
  const [activeMobileView, setActiveMobileView] = useState<MobileView>("tools");
  const isProgrammaticScroll = useRef(false);
  const [configModalOpen, setConfigModalOpen] = useState(false);
-  const [showAnalyticsModal, setShowAnalyticsModal] = useState(false);

  const { activeFiles } = useFileContext();
  const { actions } = useNavigationActions();
  const { setActiveFileIndex } = useViewer();
  const prevFileCountRef = useRef(activeFiles.length);

-  // Show admin analytics choice modal if analytics settings not configured
-  useEffect(() => {
-    if (config && config.enableAnalytics === null) {
-      setShowAnalyticsModal(true);
-    }
-  }, [config]);
-
  // Auto-switch to viewer when going from 0 to 1 file
  useEffect(() => {
    const prevCount = prevFileCountRef.current;
@@ -181,10 +172,6 @@ export default function HomePage() {

  return (
    <div className="h-screen overflow-hidden">
-      <AdminAnalyticsChoiceModal
-        opened={showAnalyticsModal}
-        onClose={() => setShowAnalyticsModal(false)}
-      />
      {isMobile ? (
        <div className="mobile-layout">
          <div className="mobile-toggle">
@@ -9,11 +9,26 @@ export interface AccountData {
  saml2Login: boolean;
 }

+export interface LoginPageData {
+  showDefaultCredentials: boolean;
+  firstTimeSetup: boolean;
+  enableLogin: boolean;
+}
+
 /**
 * Account Service
 * Provides functions to interact with account-related backend APIs
 */
 export const accountService = {
+  /**
+   * Get login page data (includes showDefaultCredentials flag)
+   * This is a public endpoint - doesn't require authentication
+   */
+  async getLoginPageData(): Promise<LoginPageData> {
+    const response = await apiClient.get<LoginPageData>('/api/v1/proprietary/ui-data/login');
+    return response.data;
+  },
+
  /**
   * Get current user account data
   */
@@ -4,6 +4,8 @@
 export const Z_INDEX_FULLSCREEN_SURFACE = 1000;
 export const Z_INDEX_OVER_FULLSCREEN_SURFACE = 1300;
 export const Z_ANALYTICS_MODAL = 1301;
+// Config/Settings modal - should appear above analytics modal when navigating from onboarding
+export const Z_INDEX_CONFIG_MODAL = 1400;

 export const Z_INDEX_FILE_MANAGER_MODAL = 1200;
 export const Z_INDEX_OVER_FILE_MANAGER_MODAL = 1300;
@@ -10,7 +10,7 @@ import { CONVERSION_ENDPOINTS } from '@app/constants/convertConstants';
 import apiClient from '@app/services/apiClient';
 import { downloadBlob, downloadTextAsFile } from '@app/utils/downloadUtils';
 import { getFilenameFromHeaders } from '@app/utils/fileResponseUtils';
-import { pdfWorkerManager } from '@core/services/pdfWorkerManager';
+import { pdfWorkerManager } from '@app/services/pdfWorkerManager';
 import { Util } from 'pdfjs-dist/legacy/build/pdf.mjs';
 import {
  PdfJsonDocument,
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Anthony Stirling	2b173a030e	text fixing	2025-12-03 10:48:13 +00:00
Anthony Stirling	c5525d8676	Merge remote-tracking branch 'origin/V2' into latex2	2025-12-03 09:07:42 +00:00
Reece BrowneandGitHub	c3456adc2b	Print with embed (#5109 )	2025-12-02 13:56:28 +00:00
EthanHealy01andGitHub	179b569769	Chore/v2/onboarding flow cleanup (#5065 )	2025-12-02 12:40:20 +00:00
Dario Ghunney Ware GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>Ludy EthanHealy01 Ethan Anthony Stirlingstirlingbot[bot] <195170888+stirlingbot[bot]@users.noreply.github.com>	341adaa07d	Grandpa Fix (#5030 ) PR to address inactive accounts (invited/pending activation) not being grandfathered during migration --------- Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: stirlingbot[bot] <stirlingbot[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ludy <Ludy87@users.noreply.github.com> Co-authored-by: EthanHealy01 <80844253+EthanHealy01@users.noreply.github.com> Co-authored-by: Ethan <ethan@MacBook-Pro.local> Co-authored-by: Anthony Stirling <77850077+Frooodle@users.noreply.github.com> Co-authored-by: stirlingbot[bot] <195170888+stirlingbot[bot]@users.noreply.github.com>	2025-12-02 12:34:38 +00:00
Dario Ghunney Ware GitHubdependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>Ludy EthanHealy01 Ethan Anthony Stirlingstirlingbot[bot] <195170888+stirlingbot[bot]@users.noreply.github.com>	feebfe82fa	Reduce JWT Logs (#5108 ) Removed logging in some areas and changed level from `WARN` -> `DEBUG` to reduce verbosity Closes #5089 --------- Signed-off-by: dependabot[bot] <support@github.com> Signed-off-by: stirlingbot[bot] <stirlingbot[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Ludy <Ludy87@users.noreply.github.com> Co-authored-by: EthanHealy01 <80844253+EthanHealy01@users.noreply.github.com> Co-authored-by: Ethan <ethan@MacBook-Pro.local> Co-authored-by: Anthony Stirling <77850077+Frooodle@users.noreply.github.com> Co-authored-by: stirlingbot[bot] <195170888+stirlingbot[bot]@users.noreply.github.com>	2025-12-02 12:34:17 +00:00