@prabhask5/stellar-engine 1.1.8 → 1.1.10

package/dist/bin/install-pwa.js

@@ -12,18 +12,21 @@
  *
  * Files are written non-destructively: existing files are skipped, not overwritten.
  *
+ * Launches an interactive walkthrough when invoked as `stellar-engine install pwa`.
+ *
  * @example
  * ```bash
- * stellar-engine install pwa --name "App Name" --short_name "Short" --prefix "myprefix" [--description "..."]
+ * stellar-engine install pwa
  * ```
  *
  * @see {@link main} for the entry point
- * @see {@link parseArgs} for CLI argument parsing
+ * @see {@link runInteractiveSetup} for the interactive walkthrough
  * @see {@link writeIfMissing} for the non-destructive file write strategy
  */
 import { writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { execSync } from 'child_process';
+import { createInterface } from 'readline';
 // =============================================================================
 //                                 HELPERS
 // =============================================================================
@@ -37,12 +40,14 @@ import { execSync } from 'child_process';
  * @param content - The file content to write.
  * @param createdFiles - Accumulator for newly-created file paths (relative).
  * @param skippedFiles - Accumulator for skipped file paths (relative).
+ * @param quiet - When `true`, suppresses per-file console output (used during animated progress).
  */
-function writeIfMissing(filePath, content, createdFiles, skippedFiles) {
+function writeIfMissing(filePath, content, createdFiles, skippedFiles, quiet = false) {
     const relPath = filePath.replace(process.cwd() + '/', '');
     if (existsSync(filePath)) {
         skippedFiles.push(relPath);
-        console.log(`  [skip] ${relPath} already exists`);
+        if (!quiet)
+            console.log(`  [skip] ${relPath} already exists`);
     }
     else {
         const dir = filePath.substring(0, filePath.lastIndexOf('/'));
@@ -51,59 +56,239 @@ function writeIfMissing(filePath, content, createdFiles, skippedFiles) {
         }
         writeFileSync(filePath, content, 'utf-8');
         createdFiles.push(relPath);
-        console.log(`  [write] ${relPath}`);
+        if (!quiet)
+            console.log(`  [write] ${relPath}`);
+    }
+}
+// =============================================================================
+//                           ANSI STYLE HELPERS
+// =============================================================================
+/** Wrap text in ANSI bold. */
+const bold = (s) => `\x1b[1m${s}\x1b[22m`;
+/** Wrap text in ANSI dim. */
+const dim = (s) => `\x1b[2m${s}\x1b[22m`;
+/** Wrap text in ANSI cyan. */
+const cyan = (s) => `\x1b[36m${s}\x1b[39m`;
+/** Wrap text in ANSI green. */
+const green = (s) => `\x1b[32m${s}\x1b[39m`;
+/** Wrap text in ANSI yellow. */
+const yellow = (s) => `\x1b[33m${s}\x1b[39m`;
+/** Wrap text in ANSI red. */
+const red = (s) => `\x1b[31m${s}\x1b[39m`;
+/**
+ * Draw a box around lines of text using Unicode box-drawing characters.
+ *
+ * @param lines - The lines of text to display inside the box.
+ * @param style - `"double"` for `╔═╗║╚═╝`, `"single"` for `┌─┐│└─┘`.
+ * @param title - Optional title to display in the top border.
+ * @returns The formatted box string with leading two-space indent.
+ */
+function box(lines, style, title) {
+    const [tl, h, tr, v, bl, br] = style === 'double'
+        ? ['\u2554', '\u2550', '\u2557', '\u2551', '\u255a', '\u255d']
+        : ['\u250c', '\u2500', '\u2510', '\u2502', '\u2514', '\u2518'];
+    const width = Math.max(...lines.map((l) => l.length), (title ?? '').length + 4, 50);
+    let top;
+    if (title) {
+        const titleStr = `${h} ${title} `;
+        top = `  ${tl}${titleStr}${h.repeat(width - titleStr.length)}${tr}`;
     }
+    else {
+        top = `  ${tl}${h.repeat(width)}${tr}`;
+    }
+    const mid = lines.map((l) => `  ${v} ${l.padEnd(width - 2)}${v}`).join('\n');
+    const bot = `  ${bl}${h.repeat(width)}${br}`;
+    return `${top}\n${mid}\n${bot}`;
+}
+/**
+ * Draw a double-bordered box with a header and body separated by a mid-rule.
+ *
+ * @param header - The header line(s) to display above the divider.
+ * @param body - The body lines to display below the divider.
+ * @returns The formatted box string with leading two-space indent.
+ */
+function doubleBoxWithHeader(header, body) {
+    const width = Math.max(...header.map((l) => l.length), ...body.map((l) => l.length), 50);
+    const top = `  \u2554${'═'.repeat(width)}\u2557`;
+    const headLines = header.map((l) => `  \u2551 ${l.padEnd(width - 2)}\u2551`).join('\n');
+    const mid = `  \u2560${'═'.repeat(width)}\u2563`;
+    const bodyLines = body.map((l) => `  \u2551 ${l.padEnd(width - 2)}\u2551`).join('\n');
+    const bot = `  \u255a${'═'.repeat(width)}\u255d`;
+    return `${top}\n${headLines}\n${mid}\n${bodyLines}\n${bot}`;
+}
+// =============================================================================
+//                              SPINNER
+// =============================================================================
+/** Braille spinner frames for animated progress. */
+const SPINNER_FRAMES = [
+    '\u280b',
+    '\u2819',
+    '\u2839',
+    '\u2838',
+    '\u283c',
+    '\u2834',
+    '\u2826',
+    '\u2827',
+    '\u2807',
+    '\u280f'
+];
+/**
+ * Create a terminal spinner that updates a single line in-place.
+ *
+ * @param text - Initial text to display beside the spinner.
+ * @returns An object with `update`, `succeed`, and `stop` methods.
+ */
+function createSpinner(text) {
+    let frame = 0;
+    let current = text;
+    let timer = null;
+    const render = () => {
+        const spinner = cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length]);
+        process.stdout.write(`\r  ${spinner} ${current}`);
+        frame++;
+    };
+    timer = setInterval(render, 80);
+    render();
+    return {
+        update(newText) {
+            current = newText;
+        },
+        succeed(finalText) {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            process.stdout.write(`\r  ${green('\u2713')} ${finalText}\x1b[K\n`);
+        },
+        stop() {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+            process.stdout.write('\x1b[K');
+        }
+    };
 }
 // =============================================================================
-//                              ARG PARSING
+//                         INTERACTIVE SETUP
 // =============================================================================
 /**
- * Parse command-line arguments into an {@link InstallOptions} object.
+ * Promisified readline question helper.
  *
- * Expects the format:
- *   `stellar-engine install pwa --name "..." --short_name "..." --prefix "..." [--description "..."]`
+ * @param rl - The readline interface.
+ * @param prompt - The prompt string to display.
+ * @returns The user's input string.
+ */
+function ask(rl, prompt) {
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => resolve(answer));
+    });
+}
+/**
+ * Run the interactive setup walkthrough, collecting all required options
+ * from the user via sequential prompts.
  *
- * Exits the process with a usage message if required arguments are missing.
+ * Displays a welcome banner, then prompts for App Name, Short Name, Prefix,
+ * and Description with inline validation. Shows a confirmation summary and
+ * asks the user to proceed before returning.
  *
- * @param argv - The raw `process.argv` array.
- * @returns The parsed {@link InstallOptions}.
+ * @returns A promise that resolves with the validated {@link InstallOptions}.
  *
- * @throws {SystemExit} Exits with code 1 if `--name`, `--short_name`, or `--prefix` are missing.
+ * @throws {SystemExit} Exits with code 0 if the user declines to proceed.
  */
-function parseArgs(argv) {
-    const args = argv.slice(2);
-    if (args[0] !== 'install' || args[1] !== 'pwa') {
-        console.error('Usage: stellar-engine install pwa --name "App Name" --short_name "Short" --prefix "myprefix" [--description "..."]');
-        process.exit(1);
-    }
+async function runInteractiveSetup() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    /* ── Welcome banner ── */
+    console.log();
+    console.log(doubleBoxWithHeader([`       ${bold('\u2726 stellar-engine \u00b7 PWA scaffolder \u2726')}`], [
+        'Creates a complete offline-first SvelteKit PWA ',
+        'with auth, sync, and service worker support.   '
+    ]));
+    console.log();
+    /* ── App Name ── */
     let name = '';
+    while (!name) {
+        console.log(box([
+            'The full name of your application.             ',
+            'Used in the page title, README, and manifest.  ',
+            `Example: ${dim('"Stellar Planner"')}                       `
+        ], 'single', 'App Name'));
+        const input = (await ask(rl, `  ${yellow('\u2192')} App name: `)).trim();
+        if (!input) {
+            console.log(red('  App name is required.\n'));
+        }
+        else {
+            name = input;
+        }
+    }
+    console.log();
+    /* ── Short Name ── */
     let shortName = '';
-    let prefix = '';
-    let description = 'A self-hosted offline-first PWA';
-    for (let i = 2; i < args.length; i++) {
-        switch (args[i]) {
-            case '--name':
-                name = args[++i];
-                break;
-            case '--short_name':
-                shortName = args[++i];
-                break;
-            case '--prefix':
-                prefix = args[++i];
-                break;
-            case '--description':
-                description = args[++i];
-                break;
+    while (!shortName) {
+        console.log(box([
+            'A short label for the home screen and app bar. ',
+            'Must be under 12 characters.                   ',
+            `Example: ${dim('"Stellar"')}                               `
+        ], 'single', 'Short Name'));
+        const input = (await ask(rl, `  ${yellow('\u2192')} Short name: `)).trim();
+        if (!input) {
+            console.log(red('  Short name is required.\n'));
+        }
+        else if (input.length >= 12) {
+            console.log(red('  Short name must be under 12 characters.\n'));
+        }
+        else {
+            shortName = input;
         }
     }
-    if (!name || !shortName || !prefix) {
-        console.error('Error: --name, --short_name, and --prefix are required.\n' +
-            'Usage: stellar-engine install pwa --name "App Name" --short_name "Short" --prefix "myprefix" [--description "..."]');
-        process.exit(1);
+    console.log();
+    /* ── Prefix ── */
+    const suggestedPrefix = name.toLowerCase().replace(/[^a-z0-9]/g, '');
+    let prefix = '';
+    while (!prefix) {
+        console.log(box([
+            'Lowercase key used for localStorage, caches,   ',
+            'and the service worker scope.                   ',
+            'No spaces. Letters and numbers only.            ',
+            `Suggested: ${dim(`"${suggestedPrefix}"`)}${' '.repeat(Math.max(0, 36 - suggestedPrefix.length - 3))}`
+        ], 'single', 'Prefix'));
+        const input = (await ask(rl, `  ${yellow('\u2192')} Prefix ${dim(`(${suggestedPrefix})`)}: `)).trim();
+        const value = input || suggestedPrefix;
+        if (!/^[a-z][a-z0-9]*$/.test(value)) {
+            console.log(red('  Prefix must be lowercase, start with a letter, no spaces.\n'));
+        }
+        else {
+            prefix = value;
+        }
     }
+    console.log();
+    /* ── Description ── */
+    const defaultDesc = 'A self-hosted offline-first PWA';
+    console.log(box([
+        'A brief description for meta tags and manifest. ',
+        `Press Enter to use the default.                 `,
+        `Default: ${dim(`"${defaultDesc}"`)}`
+    ], 'single', 'Description'));
+    const descInput = (await ask(rl, `  ${yellow('\u2192')} Description ${dim('(optional)')}: `)).trim();
+    const description = descInput || defaultDesc;
+    console.log();
     /* Derive kebab-case name for package.json from the full name */
     const kebabName = name.toLowerCase().replace(/\s+/g, '-');
-    return { name, shortName, prefix, description, kebabName };
+    const opts = { name, shortName, prefix, description, kebabName };
+    /* ── Confirmation summary ── */
+    console.log(box([
+        `${bold('Name:')}         ${opts.name}${' '.repeat(Math.max(0, 38 - opts.name.length))}`,
+        `${bold('Short name:')}   ${opts.shortName}${' '.repeat(Math.max(0, 38 - opts.shortName.length))}`,
+        `${bold('Prefix:')}       ${opts.prefix}${' '.repeat(Math.max(0, 38 - opts.prefix.length))}`,
+        `${bold('Description:')}  ${opts.description}${' '.repeat(Math.max(0, 38 - opts.description.length))}`
+    ], 'single', 'Configuration'));
+    const proceed = (await ask(rl, `  Proceed? ${dim('(Y/n)')}: `)).trim().toLowerCase();
+    if (proceed === 'n' || proceed === 'no') {
+        console.log(dim('\n  Setup cancelled.\n'));
+        rl.close();
+        process.exit(0);
+    }
+    rl.close();
+    console.log();
+    return opts;
 }
 // =============================================================================
 //                          TEMPLATE GENERATORS
@@ -1239,7 +1424,7 @@ export const prerender = false;
 //     },
 //     supabase,
 //     prefix: '${opts.prefix}',
-//     auth: { mode: 'single-user', singleUser: { gateType: 'code', codeLength: 6 } },
+//     auth: { singleUser: { gateType: 'code', codeLength: 6 } },
 //     onAuthStateChange: (event, session) => { /* handle auth events */ },
 //     onAuthKicked: async () => { await lockSingleUser(); goto('/login'); }
 //   });
@@ -1301,7 +1486,7 @@ export const load: LayoutLoad = async ({ url }): Promise<LayoutData> => {
  *
  * @returns The Svelte component source for `src/routes/+layout.svelte`.
  */
-function generateRootLayoutSvelte() {
+function generateRootLayoutSvelte(opts) {
     return `<!--
   @fileoverview Root layout component — app shell, auth hydration,
   navigation chrome, overlays, and PWA lifecycle.
@@ -1313,48 +1498,236 @@ function generateRootLayoutSvelte() {
 -->
 <script lang="ts">
   /**
-   * @fileoverview Root layout script — imports, props, and reactive auth hydration.
+   * @fileoverview Root layout script — auth state management, navigation logic,
+   * service worker communication, and global event handlers.
    */
 
-  // ==========================================================================
-  //                                IMPORTS
-  // ==========================================================================
+  // =============================================================================
+  //  Imports
+  // =============================================================================
+
+  /* ── Svelte Lifecycle & Transitions ── */
+  import { onMount, onDestroy } from 'svelte';
+
+  /* ── SvelteKit Utilities ── */
+  import { page } from '$app/stores';
+  import { browser } from '$app/environment';
 
   /* ── Stellar Engine — Auth & Stores ── */
+  import { lockSingleUser } from '@prabhask5/stellar-engine/auth';
+  import { debug } from '@prabhask5/stellar-engine/utils';
   import { hydrateAuthState } from '@prabhask5/stellar-engine/kit';
-  import { authState } from '@prabhask5/stellar-engine/stores';
 
   /* ── Types ── */
   import type { LayoutData } from './+layout';
 
-  // ==========================================================================
-  //                                 PROPS
-  // ==========================================================================
+  // =============================================================================
+  //  Props
+  // =============================================================================
 
   interface Props {
-    /** Default slot content (the routed page component). */
+    /** Default slot content — the matched page component. */
     children?: import('svelte').Snippet;
-    /** Layout data returned by the root \`+layout.ts\` load function. */
+
+    /** Layout data from \`+layout.ts\` — session, auth mode, offline profile. */
     data: LayoutData;
   }
 
   let { children, data }: Props = $props();
 
-  // ==========================================================================
-  //                           COMPONENT STATE
-  // ==========================================================================
+  // =============================================================================
+  //  Component State
+  // =============================================================================
+
+  /* ── Toast Notification ── */
+  /** Whether the toast notification is currently visible. */
+  let showToast = $state(false);
+
+  /** The text content of the current toast notification. */
+  let toastMessage = $state('');
+
+  /** The visual style of the toast — \`'info'\` (purple) or \`'error'\` (pink). */
+  let toastType = $state<'info' | 'error'>('info');
+
+  /* ── Sign-Out ── */
+  /** When \`true\`, a full-screen overlay is shown to mask the sign-out transition. */
+  let isSigningOut = $state(false);
+
+  /* ── Cleanup References ── */
+  /** Stored reference to the chunk error handler so we can remove it on destroy. */
+  let chunkErrorHandler: ((event: PromiseRejectionEvent) => void) | null = null;
+
+  // =============================================================================
+  //  Reactive Effects
+  // =============================================================================
 
   /**
-   * Hydrate the global auth store whenever the load function returns
-   * fresh data (e.g. after navigation or token refresh).
+   * Effect: hydrate the global \`authState\` store from layout load data.
+   *
+   * Runs whenever \`data\` changes (e.g. after navigation or revalidation).
+   * Maps the three possible auth modes to the corresponding store setter:
+   * - \`'supabase'\` + session → \`setSupabaseAuth\`
+   * - \`'offline'\` + cached profile → \`setOfflineAuth\`
+   * - anything else → \`setNoAuth\`
    */
   $effect(() => {
     hydrateAuthState(data);
   });
 
-  // TODO: Add app shell (navbar, tab bar, overlays, sign-out logic, etc.)
-  // TODO: Import and use UpdatePrompt from '$lib/components/UpdatePrompt.svelte'
-  // TODO: Import and use SyncStatus from '@prabhask5/stellar-engine/components/SyncStatus'
+  // =============================================================================
+  //  Lifecycle — Mount
+  // =============================================================================
+
+  onMount(() => {
+    // ── Chunk Error Handler ────────────────────────────────────────────────
+    // When navigating offline to a page whose JS chunks aren't cached,
+    // the dynamic import fails and shows a cryptic error. Catch and show a friendly message.
+    chunkErrorHandler = (event: PromiseRejectionEvent) => {
+      const error = event.reason;
+      // Check if this is a chunk loading error (fetch failed or syntax error from 503 response)
+      const isChunkError =
+        error?.message?.includes('Failed to fetch dynamically imported module') ||
+        error?.message?.includes('error loading dynamically imported module') ||
+        error?.message?.includes('Importing a module script failed') ||
+        error?.name === 'ChunkLoadError' ||
+        (error?.message?.includes('Loading chunk') && error?.message?.includes('failed'));
+
+      if (isChunkError && !navigator.onLine) {
+        event.preventDefault(); // Prevent default error handling
+        // Show offline navigation toast
+        toastMessage = "This page isn't available offline. Please reconnect or go back.";
+        toastType = 'info';
+        showToast = true;
+        setTimeout(() => {
+          showToast = false;
+        }, 5000);
+      }
+    };
+
+    window.addEventListener('unhandledrejection', chunkErrorHandler);
+
+    // ── Sign-Out Event Listener ───────────────────────────────────────────
+    // Listen for sign out requests from child pages (e.g. mobile profile page)
+    window.addEventListener('${opts.prefix}:signout', handleSignOut);
+
+    // ── Service Worker — Background Precaching ────────────────────────────
+    // Proactively cache all app chunks for full offline support.
+    // This runs in the background after page load, so it doesn't affect Lighthouse scores.
+    if ('serviceWorker' in navigator) {
+      // Listen for precache completion messages from service worker
+      navigator.serviceWorker.addEventListener('message', (event) => {
+        if (event.data?.type === 'PRECACHE_COMPLETE') {
+          const { cached, total } = event.data;
+          debug('log', \`[PWA] Background precaching complete: \${cached}/\${total} assets cached\`);
+          if (cached === total) {
+            debug('log', '[PWA] Full offline support ready - all pages accessible offline');
+          } else {
+            debug('warn', \`[PWA] Some assets failed to cache: \${total - cached} missing\`);
+          }
+        }
+      });
+
+      // Wait for service worker to be ready (handles first load case)
+      navigator.serviceWorker.ready.then((registration) => {
+        debug('log', '[PWA] Service worker ready, scheduling background precache...');
+
+        // Give the page time to fully load, then trigger background precaching
+        setTimeout(() => {
+          const controller = navigator.serviceWorker.controller || registration.active;
+          if (!controller) {
+            debug('warn', '[PWA] No service worker controller available');
+            return;
+          }
+
+          // First, cache current page's assets (scripts + stylesheets)
+          const scripts = Array.from(document.querySelectorAll('script[src]'))
+            .map((el) => (el as HTMLScriptElement).src)
+            .filter((src) => src.startsWith(location.origin));
+
+          const styles = Array.from(document.querySelectorAll('link[rel="stylesheet"]'))
+            .map((el) => (el as HTMLLinkElement).href)
+            .filter((href) => href.startsWith(location.origin));
+
+          const urls = [...scripts, ...styles];
+
+          if (urls.length > 0) {
+            debug('log', \`[PWA] Caching \${urls.length} current page assets...\`);
+            controller.postMessage({
+              type: 'CACHE_URLS',
+              urls
+            });
+          }
+
+          // Then trigger full background precaching for all app chunks.
+          // This ensures offline support for all pages, not just visited ones.
+          debug('log', '[PWA] Triggering background precache of all app chunks...');
+          controller.postMessage({
+            type: 'PRECACHE_ALL'
+          });
+        }, 500); // Cache assets quickly to reduce window for uncached refreshes
+      });
+    }
+  });
+
+  // =============================================================================
+  //  Lifecycle — Destroy
+  // =============================================================================
+
+  onDestroy(() => {
+    if (browser) {
+      // Cleanup chunk error handler
+      if (chunkErrorHandler) {
+        window.removeEventListener('unhandledrejection', chunkErrorHandler);
+      }
+      // Cleanup sign out listener
+      window.removeEventListener('${opts.prefix}:signout', handleSignOut);
+    }
+  });
+
+  // =============================================================================
+  //  Event Handlers
+  // =============================================================================
+
+  /**
+   * Handles the sign-out flow with a visual transition.
+   *
+   * 1. Shows a full-screen "Locking..." overlay immediately.
+   * 2. Waits 250ms for the overlay fade-in to complete.
+   * 3. Calls \`lockSingleUser()\` to stop the engine and clear the session
+   *    (but NOT destroy user data).
+   * 4. Hard-navigates to \`/login\` (full page reload to reset all state).
+   */
+  async function handleSignOut() {
+    // Show full-screen overlay immediately
+    isSigningOut = true;
+
+    // Wait for overlay to fully appear
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    // Lock the single-user session (stops engine, resets auth state, does NOT destroy data)
+    await lockSingleUser();
+
+    // Navigate to login
+    window.location.href = '/login';
+  }
+
+  /**
+   * Checks whether a given route \`href\` matches the current page path.
+   * Used to highlight the active nav item.
+   *
+   * @param href - The route path to check (e.g. \`'/agenda'\`)
+   * @returns \`true\` if the current path starts with \`href\`
+   */
+  function isActive(href: string): boolean {
+    return $page.url.pathname.startsWith(href);
+  }
+
+  /**
+   * Dismisses the currently visible toast notification.
+   */
+  function dismissToast() {
+    showToast = false;
+  }
 </script>
 
 <!-- TODO: Add your app shell template (navbar, tab bar, page transitions, etc.) -->
@@ -1369,7 +1742,7 @@ function generateRootLayoutSvelte() {
  *
  * @returns The Svelte component source for `src/routes/+page.svelte`.
  */
-function generateHomePage() {
+function generateHomePage(opts) {
     return `<!--
   @fileoverview Home / landing page — welcome screen and primary content.
 
@@ -1401,9 +1774,31 @@ function generateHomePage() {
     resolveFirstName($authState.session, $authState.offlineProfile)
   );
 
+    // =============================================================================
+  //  Reactive Effects
+  // =============================================================================
+
+  /**
+   * Effect: auth redirect guard.
+   *
+   * Once the auth store finishes loading and resolves to \`'none'\` (no session),
+   * redirect to \`/login\` with a \`redirect\` query param so the login page knows
+   * this was an automatic redirect rather than direct navigation.
+   */
+  $effect(() => {
+    if (!$authState.isLoading && $authState.mode === 'none') {
+      // Include redirect param so login page knows this was a redirect, not direct navigation
+      goto('/login?redirect=%2F', { replaceState: true });
+    }
+  });
+
   // TODO: Add home page state and logic
 </script>
 
+<svelte:head>
+  <title>Home - ${opts.name}</title>
+</svelte:head>
+
 <!-- TODO: Add home page template -->
 `;
 }
@@ -1412,7 +1807,7 @@ function generateHomePage() {
  *
  * @returns The Svelte component source for `src/routes/+error.svelte`.
  */
-function generateErrorPage() {
+function generateErrorPage(opts) {
     return `<!--
   @fileoverview Error boundary — handles three scenarios:
     1. **Offline** — device has no connectivity, show a friendly offline message
@@ -1434,26 +1829,68 @@ function generateErrorPage() {
   //                                 STATE
   // ==========================================================================
 
-  // TODO: Add error page logic (offline detection, retry handlers, etc.)
+  /** Whether the user is currently offline — drives which error variant is shown. */
+  let isOffline = $state(false);
 
   // ==========================================================================
   //                          REACTIVE EFFECTS
   // ==========================================================================
 
-  // TODO: Add reactive effects (e.g. watch online/offline status)
+  /**
+   * Effect: tracks the browser's online/offline status in real time.
+   * Sets \`isOffline\` on mount and attaches \`online\` / \`offline\` event listeners.
+   * Returns a cleanup function that removes the listeners on destroy.
+   */
+  $effect(() => {
+    if (browser) {
+      isOffline = !navigator.onLine;
+
+      const handleOnline = () => {
+        isOffline = false;
+      };
+      const handleOffline = () => {
+        isOffline = true;
+      };
+
+      window.addEventListener('online', handleOnline);
+      window.addEventListener('offline', handleOffline);
+
+      return () => {
+        window.removeEventListener('online', handleOnline);
+        window.removeEventListener('offline', handleOffline);
+      };
+    }
+  });
 
   // ==========================================================================
   //                          EVENT HANDLERS
   // ==========================================================================
 
-  // TODO: Add event handlers (retry, go home, etc.)
+  /**
+   * Reload the current page — useful when the user regains connectivity or
+   * wants to retry after a transient server error.
+   */
+  function handleRetry() {
+    window.location.reload();
+  }
+
+  /**
+   * Navigate back to the home page via SvelteKit client-side routing.
+   */
+  function handleGoHome() {
+    goto('/');
+  }
 </script>
 
+<svelte:head>
+  <title>Error - ${opts.name}</title>
+</svelte:head>
+
 <!-- TODO: Add error page template (status code display, retry button, go home button) -->
 `;
 }
 /**
- * Generate the setup page load function with first-setup / admin-only guard.
+ * Generate the setup page load function with first-setup / auth guard.
  *
  * @returns The TypeScript source for `src/routes/setup/+page.ts`.
  */
@@ -1464,18 +1901,18 @@ function generateSetupPageTs() {
  * Two modes:
  *   - **Unconfigured** — no runtime config exists yet; anyone can access the
  *     setup wizard to perform first-time Supabase configuration.
- *   - **Configured + admin** — config already saved; only authenticated admin
- *     users may revisit the setup page to update credentials or redeploy.
+ *   - **Configured** — config already saved; only authenticated users may
+ *     revisit the setup page to update credentials or redeploy.
  */
 
 import { browser } from '$app/environment';
 import { redirect } from '@sveltejs/kit';
 import { getConfig } from '@prabhask5/stellar-engine/config';
-import { getValidSession, isAdmin } from '@prabhask5/stellar-engine/auth';
+import { getValidSession } from '@prabhask5/stellar-engine/auth';
 import type { PageLoad } from './$types';
 
 /**
- * Guard the setup route — allow first-time setup or admin-only access.
+ * Guard the setup route — allow first-time setup or authenticated access.
  *
  * @returns Page data with an \`isFirstSetup\` flag.
  */
@@ -1489,9 +1926,6 @@ export const load: PageLoad = async () => {
   if (!session?.user) {
     redirect(307, '/login');
   }
-  if (!isAdmin(session.user)) {
-    redirect(307, '/');
-  }
   return { isFirstSetup: false };
 };
 `;
@@ -1501,7 +1935,7 @@ export const load: PageLoad = async () => {
  *
  * @returns The Svelte component source for `src/routes/setup/+page.svelte`.
  */
-function generateSetupPageSvelte() {
+function generateSetupPageSvelte(opts) {
     return `<!--
   @fileoverview Five-step Supabase configuration wizard.
 
@@ -1510,13 +1944,219 @@ function generateSetupPageSvelte() {
   and reloading the app with the new config active.
 -->
 <script lang="ts">
+  /**
+   * @fileoverview Setup wizard page — first-time Supabase configuration.
+   *
+   * Guides the user through a five-step process to connect their own
+   * Supabase backend to Stellar:
+   *
+   * 1. Create a Supabase project (instructions only).
+   * 2. Configure authentication (enable anonymous sign-ins).
+   * 3. Initialize the database by running the schema SQL.
+   * 4. Enter and validate Supabase credentials (URL + anon key).
+   * 5. Persist configuration via Vercel API (set env vars + redeploy).
+   *
+   * After a successful deploy the page polls for a new service-worker
+   * version — once detected the user is prompted to refresh.
+   *
+   * Access is controlled by the companion \`+page.ts\` load function:
+   * - Unconfigured → anyone can reach this page (\`isFirstSetup: true\`).
+   * - Configured → authenticated users only (\`isFirstSetup: false\`).
+   */
+
+  import { page } from '$app/stores';
   import { setConfig } from '@prabhask5/stellar-engine/config';
   import { isOnline } from '@prabhask5/stellar-engine/stores';
   import { pollForNewServiceWorker } from '@prabhask5/stellar-engine/kit';
 
-  // TODO: Add setup wizard state (steps, form fields, validation, deployment)
+  // =============================================================================
+  //  Form State — Supabase + Vercel credentials
+  // =============================================================================
+
+  /** Supabase project URL entered by the user */
+  let supabaseUrl = $state('');
+
+  /** Supabase public anon key entered by the user */
+  let supabaseAnonKey = $state('');
+
+  /** One-time Vercel API token for setting env vars */
+  let vercelToken = $state('');
+
+  // =============================================================================
+  //  UI State — Validation & Deployment feedback
+  // =============================================================================
+
+  /** Whether the "Test Connection" request is in-flight */
+  let validating = $state(false);
+
+  /** Whether the deploy/redeploy flow is in-flight */
+  let deploying = $state(false);
+
+  /** Error from credential validation, if any */
+  let validateError = $state<string | null>(null);
+
+  /** \`true\` after credentials have been successfully validated */
+  let validateSuccess = $state(false);
+
+  /** Error from the deployment step, if any */
+  let deployError = $state<string | null>(null);
+
+  /** Current deployment pipeline stage — drives the progress UI */
+  let deployStage = $state<'idle' | 'setting-env' | 'deploying' | 'ready'>('idle');
+
+  /** URL returned by Vercel for the triggered deployment (informational) */
+  let _deploymentUrl = $state('');
+
+  // =============================================================================
+  //  Derived State
+  // =============================================================================
+
+  /** Whether this is a first-time setup (public) or reconfiguration */
+  const isFirstSetup = $derived(($page.data as { isFirstSetup?: boolean }).isFirstSetup ?? false);
+
+  /**
+   * Snapshot of the credentials at validation time — used to detect
+   * if the user edits the inputs *after* a successful validation.
+   */
+  let validatedUrl = $state('');
+  let validatedKey = $state('');
+
+  /**
+   * \`true\` when the user changes credentials after a successful
+   * validation — the "Continue" button should be re-disabled.
+   */
+  const credentialsChanged = $derived(
+    validateSuccess && (supabaseUrl !== validatedUrl || supabaseAnonKey !== validatedKey)
+  );
+
+  // =============================================================================
+  //  Effects
+  // =============================================================================
+
+  /**
+   * Auto-reset validation state when the user modifies credentials
+   * after they were already validated — forces re-validation.
+   */
+  $effect(() => {
+    if (credentialsChanged) {
+      validateSuccess = false;
+      validateError = null;
+    }
+  });
+
+  // =============================================================================
+  //  Validation — "Test Connection"
+  // =============================================================================
+
+  /**
+   * Send the entered Supabase credentials to \`/api/setup/validate\`
+   * and update UI state based on the result. On success, also
+   * cache the config locally via \`setConfig\` so the app is usable
+   * immediately after the deployment finishes.
+   */
+  async function handleValidate() {
+    validateError = null;
+    validateSuccess = false;
+    validating = true;
+
+    try {
+      const res = await fetch('/api/setup/validate', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ supabaseUrl, supabaseAnonKey })
+      });
+
+      const data = await res.json();
+
+      if (data.valid) {
+        validateSuccess = true;
+        validatedUrl = supabaseUrl;
+        validatedKey = supabaseAnonKey;
+        /* Cache config locally so the app works immediately after deploy */
+        setConfig({
+          supabaseUrl,
+          supabaseAnonKey,
+          configured: true
+        });
+      } else {
+        validateError = data.error || 'Validation failed';
+      }
+    } catch (e) {
+      validateError = e instanceof Error ? e.message : 'Network error';
+    }
+
+    validating = false;
+  }
+
+  // =============================================================================
+  //  Deployment Polling
+  // =============================================================================
+
+  /**
+   * Poll for a new service-worker version to detect when the Vercel
+   * redeployment has finished. Uses the engine's \`pollForNewServiceWorker\`
+   * helper which checks \`registration.update()\` at regular intervals.
+   *
+   * Resolves a Promise when a new SW is detected in the waiting state.
+   */
+  function pollForDeployment(): Promise<void> {
+    return new Promise((resolve) => {
+      pollForNewServiceWorker({
+        intervalMs: 3000,
+        maxAttempts: 200,
+        onFound: () => {
+          deployStage = 'ready';
+          resolve();
+        }
+      });
+    });
+  }
+
+  // =============================================================================
+  //  Deployment — Set env vars + trigger Vercel redeploy
+  // =============================================================================
+
+  /**
+   * Send credentials and the Vercel token to \`/api/setup/deploy\`,
+   * which sets the environment variables on the Vercel project and
+   * triggers a fresh deployment. Then poll until the new build is live.
+   */
+  async function handleDeploy() {
+    deployError = null;
+    deploying = true;
+    deployStage = 'setting-env';
+
+    try {
+      const res = await fetch('/api/setup/deploy', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ supabaseUrl, supabaseAnonKey, vercelToken })
+      });
+
+      const data = await res.json();
+
+      if (data.success) {
+        deployStage = 'deploying';
+        _deploymentUrl = data.deploymentUrl || '';
+        /* Poll for the new SW version → marks \`deployStage = 'ready'\` */
+        await pollForDeployment();
+      } else {
+        deployError = data.error || 'Deployment failed';
+        deployStage = 'idle';
+      }
+    } catch (e) {
+      deployError = e instanceof Error ? e.message : 'Network error';
+      deployStage = 'idle';
+    }
+
+    deploying = false;
+  }
 </script>
 
+<svelte:head>
+  <title>Setup - ${opts.name}</title>
+</svelte:head>
+
 <!-- TODO: Add setup wizard template (Supabase credentials form, validation, Vercel deployment) -->
 `;
 }
@@ -1525,7 +2165,7 @@ function generateSetupPageSvelte() {
  *
  * @returns The Svelte component source for `src/routes/policy/+page.svelte`.
  */
-function generatePolicyPage() {
+function generatePolicyPage(opts) {
     return `<!--
   @fileoverview Privacy policy page.
 
@@ -1536,6 +2176,10 @@ function generatePolicyPage() {
   // TODO: Add any needed imports
 </script>
 
+<svelte:head>
+  <title>Privacy Policy - ${opts.name}</title>
+</svelte:head>
+
 <!-- TODO: Add privacy policy page content -->
 `;
 }
@@ -1545,7 +2189,7 @@ function generatePolicyPage() {
  *
  * @returns The Svelte component source for `src/routes/login/+page.svelte`.
  */
-function generateLoginPage() {
+function generateLoginPage(opts) {
     return `<!--
   @fileoverview Login page — three modes:
     1. **Setup**       — first-time account creation (email + PIN)
@@ -1575,105 +2219,821 @@ function generateLoginPage() {
   //                        LAYOUT / PAGE DATA
   // ==========================================================================
 
-  // TODO: Add login page state (setup/unlock/link-device modes, PIN inputs, modals)
+  /** Whether the single-user account has already been set up on this device */
+  const singleUserSetUp = $derived($page.data.singleUserSetUp);
+
+  /** Post-login redirect URL extracted from \`?redirect=\` query param */
+  const redirectUrl = $derived($page.url.searchParams.get('redirect') || '/');
 
   // ==========================================================================
   //                          SHARED UI STATE
   // ==========================================================================
 
-  // TODO: Add BroadcastChannel listener for auth-confirmed events from /confirm
-</script>
+  /** \`true\` while any async auth operation is in-flight */
+  let loading = $state(false);
 
-<!-- TODO: Add login page template (PIN inputs, setup wizard, device verification modal) -->
-`;
-}
-/**
- * Generate the email confirmation page component that handles token
- * verification and cross-tab broadcast.
- *
- * @returns The Svelte component source for `src/routes/confirm/+page.svelte`.
- */
-function generateConfirmPage() {
-    return `<!--
-  @fileoverview Email confirmation page — token verification, BroadcastChannel
-  relay, and close/redirect flow.
+  /** Current error message shown to the user (null = no error) */
+  let error = $state<string | null>(null);
 
-  Supabase email links land here with \`?token_hash=...&type=...\` query
-  params. The page verifies the token, broadcasts the result to the
-  originating tab via BroadcastChannel, and either tells the user they
-  can close the tab or redirects them to the app root.
--->
-<script lang="ts">
-  import { onMount } from 'svelte';
-  import { goto } from '$app/navigation';
-  import { page } from '$app/stores';
-  import { handleEmailConfirmation, broadcastAuthConfirmed } from '@prabhask5/stellar-engine/kit';
+  /** Triggers the CSS shake animation on the login card */
+  let shaking = $state(false);
 
-  // ==========================================================================
-  //                                 STATE
-  // ==========================================================================
+  /** Set to \`true\` after the component mounts — enables entrance animation */
+  let mounted = $state(false);
 
-  /** Current page state — drives which UI variant is rendered. */
-  let status: 'verifying' | 'success' | 'error' | 'redirecting' | 'can_close' = 'verifying';
-  /** Human-readable error message when verification fails. */
-  let errorMessage = '';
+  // =============================================================================
+  //  Setup Mode State (step 1 → email/name, step 2 → PIN creation)
+  // =============================================================================
 
-  // ==========================================================================
-  //                              CONSTANTS
-  // ==========================================================================
+  /** User's email address for account creation */
+  let email = $state('');
 
-  /** BroadcastChannel name shared with the login page. */
-  const CHANNEL_NAME = 'auth-channel'; // TODO: Customize channel name
+  /** User's first name */
+  let firstName = $state('');
 
-  // ==========================================================================
-  //                              LIFECYCLE
-  // ==========================================================================
+  /** User's last name (optional) */
+  let lastName = $state('');
 
-  onMount(async () => {
-    /* ── Read Supabase callback params ── */
-    const tokenHash = $page.url.searchParams.get('token_hash');
-    const type = $page.url.searchParams.get('type');
+  /** Individual digit values for the 6-digit PIN code */
+  let codeDigits = $state(['', '', '', '', '', '']);
 
-    /* ── Token present → verify it ── */
-    if (tokenHash && type) {
-      const result = await handleEmailConfirmation(
-        tokenHash,
-        type as 'signup' | 'email' | 'email_change' | 'magiclink'
-      );
+  /** Individual digit values for the PIN confirmation */
+  let confirmDigits = $state(['', '', '', '', '', '']);
 
-      if (!result.success) {
-        status = 'error';
-        errorMessage = result.error || 'Unknown error';
-        return;
-      }
+  /** Concatenated PIN code — derived from \`codeDigits\` */
+  const code = $derived(codeDigits.join(''));
 
-      status = 'success';
-      /* Brief pause so the user sees the success state */
-      await new Promise((resolve) => setTimeout(resolve, 800));
-    }
+  /** Concatenated confirmation code — derived from \`confirmDigits\` */
+  const confirmCode = $derived(confirmDigits.join(''));
 
-    /* ── Notify the originating tab and decide next action ── */
-    const tabResult = await broadcastAuthConfirmed(CHANNEL_NAME, type || 'signup');
-    if (tabResult === 'can_close') {
-      status = 'can_close';
-    } else if (tabResult === 'no_broadcast') {
-      focusOrRedirect();
-    }
-  });
+  /** Current setup wizard step: 1 = email + name, 2 = PIN creation */
+  let setupStep = $state(1); // 1 = email + name, 2 = code
 
-  // ==========================================================================
-  //                              HELPERS
-  // ==========================================================================
+  // =============================================================================
+  //  Unlock Mode State (returning user on this device)
+  // =============================================================================
 
-  /**
-   * Navigate to the app root when no originating tab is available to
-   * receive the BroadcastChannel message (e.g. the user opened the
-   * confirmation link in a different browser).
-   */
-  function focusOrRedirect() {
-    goto('/', { replaceState: true });
-  }
-</script>
+  /** Individual digit values for the unlock PIN */
+  let unlockDigits = $state(['', '', '', '', '', '']);
+
+  /** Concatenated unlock code — derived from \`unlockDigits\` */
+  const unlockCode = $derived(unlockDigits.join(''));
+
+  /** Cached user profile info (first/last name) for the welcome message */
+  let userInfo = $state<{ firstName: string; lastName: string } | null>(null);
+
+  // =============================================================================
+  //  Link Device Mode State (new device, existing remote user)
+  // =============================================================================
+
+  /** Individual digit values for the device-linking PIN */
+  let linkDigits = $state(['', '', '', '', '', '']);
+
+  /** Concatenated link code — derived from \`linkDigits\` */
+  const linkCode = $derived(linkDigits.join(''));
+
+  /**
+   * Remote user info fetched from the gate config — contains email,
+   * gate type, code length, and profile data for the welcome message.
+   */
+  let remoteUser = $state<{
+    email: string;
+    gateType: string;
+    codeLength: number;
+    profile: Record<string, unknown>;
+  } | null>(null);
+
+  /** \`true\` when we detected a remote user and entered link-device mode */
+  let linkMode = $state(false);
+
+  /** Loading state specific to the link-device flow */
+  let linkLoading = $state(false);
+
+  /** \`true\` when offline and no local setup exists — shows offline card */
+  let offlineNoSetup = $state(false);
+
+  // =============================================================================
+  //  Rate-Limit Countdown State
+  // =============================================================================
+
+  /** Seconds remaining before the user can retry after a rate-limit */
+  let retryCountdown = $state(0);
+
+  /** Interval handle for the retry countdown timer */
+  let retryTimer: ReturnType<typeof setInterval> | null = null;
+
+  // =============================================================================
+  //  Modal State — Email Confirmation & Device Verification
+  // =============================================================================
+
+  /** Show the "check your email" modal after initial signup */
+  let showConfirmationModal = $state(false);
+
+  /** Show the "new device detected" verification modal */
+  let showDeviceVerificationModal = $state(false);
+
+  /** Masked email address displayed in the device-verification modal */
+  let maskedEmail = $state('');
+
+  /** Seconds remaining before the "resend" button re-enables */
+  let resendCooldown = $state(0);
+
+  /** Interval handle for the resend cooldown timer */
+  let resendTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** Interval handle for polling device verification status */
+  let verificationPollTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** Guard flag to prevent double-execution of verification completion */
+  let verificationCompleting = false; // guard against double execution
+
+  // =============================================================================
+  //  Input Refs — DOM references for focus management
+  // =============================================================================
+
+  /** References to the 6 setup-code \`<input>\` elements */
+  let codeInputs: HTMLInputElement[] = $state([]);
+
+  /** References to the 6 confirm-code \`<input>\` elements */
+  let confirmInputs: HTMLInputElement[] = $state([]);
+
+  /** References to the 6 unlock-code \`<input>\` elements */
+  let unlockInputs: HTMLInputElement[] = $state([]);
+
+  /** References to the link-code \`<input>\` elements */
+  let linkInputs: HTMLInputElement[] = $state([]);
+
+  // =============================================================================
+  //  Cross-Tab Communication
+  // =============================================================================
+
+  /** BroadcastChannel instance for receiving \`AUTH_CONFIRMED\` from \`/confirm\` */
+  let authChannel: BroadcastChannel | null = null;
+
+  // =============================================================================
+  //  Lifecycle — onMount
+  // =============================================================================
+
+  onMount(async () => {
+    mounted = true;
+
+    /* ── Existing local account → fetch user info for the welcome card ──── */
+    if (singleUserSetUp) {
+      const info = await getSingleUserInfo();
+      if (info) {
+        userInfo = {
+          firstName: (info.profile.firstName as string) || '',
+          lastName: (info.profile.lastName as string) || ''
+        };
+      }
+    } else {
+      /* ── No local setup → check for a remote user to link to ──── */
+      const isOffline = typeof navigator !== 'undefined' && !navigator.onLine;
+      if (isOffline) {
+        offlineNoSetup = true;
+      } else {
+        try {
+          const remote = await fetchRemoteGateConfig();
+          if (remote) {
+            remoteUser = remote;
+            linkMode = true;
+          }
+        } catch {
+          /* No remote user found — fall through to normal setup */
+        }
+      }
+    }
+
+    /* ── Listen for auth confirmation from the \`/confirm\` page ──── */
+    try {
+      authChannel = new BroadcastChannel('stellar-auth-channel');
+      authChannel.onmessage = async (event) => {
+        if (event.data?.type === 'AUTH_CONFIRMED') {
+          /* Bring this tab to the foreground before the confirm tab closes */
+          window.focus();
+          if (showConfirmationModal) {
+            /* Setup confirmation complete → finalize account */
+            const result = await completeSingleUserSetup();
+            if (!result.error) {
+              showConfirmationModal = false;
+              await invalidateAll();
+              goto('/');
+            } else {
+              error = result.error;
+              showConfirmationModal = false;
+            }
+          } else if (showDeviceVerificationModal) {
+            /* Device verification complete (same-browser broadcast) */
+            await handleVerificationComplete();
+          }
+        }
+      };
+    } catch {
+      /* BroadcastChannel not supported — user must manually refresh */
+    }
+  });
+
+  // =============================================================================
+  //  Lifecycle — onDestroy (cleanup timers & channels)
+  // =============================================================================
+
+  onDestroy(() => {
+    authChannel?.close();
+    if (resendTimer) clearInterval(resendTimer);
+    if (retryTimer) clearInterval(retryTimer);
+    stopVerificationPolling();
+  });
+
+  // =============================================================================
+  //  Device Verification Polling
+  // =============================================================================
+
+  /**
+   * Start polling the engine every 3 seconds to check whether the
+   * device has been trusted (the user clicked the email link on
+   * another device/browser).
+   */
+  function startVerificationPolling() {
+    stopVerificationPolling();
+    verificationPollTimer = setInterval(async () => {
+      if (verificationCompleting) return;
+      const trusted = await pollDeviceVerification();
+      if (trusted) {
+        await handleVerificationComplete();
+      }
+    }, 3000);
+  }
+
+  /**
+   * Stop the verification polling interval and clear the handle.
+   */
+  function stopVerificationPolling() {
+    if (verificationPollTimer) {
+      clearInterval(verificationPollTimer);
+      verificationPollTimer = null;
+    }
+  }
+
+  /**
+   * Finalize device verification — calls \`completeDeviceVerification\`
+   * and redirects on success. Guarded by \`verificationCompleting\` to
+   * prevent double-execution from both polling and BroadcastChannel.
+   */
+  async function handleVerificationComplete() {
+    if (verificationCompleting) return;
+    verificationCompleting = true;
+    stopVerificationPolling();
+
+    const result = await completeDeviceVerification();
+    if (!result.error) {
+      showDeviceVerificationModal = false;
+      await invalidateAll();
+      goto(redirectUrl);
+    } else {
+      error = result.error;
+      showDeviceVerificationModal = false;
+      verificationCompleting = false;
+    }
+  }
+
+  // =============================================================================
+  //  Resend & Retry Cooldowns
+  // =============================================================================
+
+  /**
+   * Start a 30-second cooldown on the "Resend email" button to
+   * prevent spamming the email service.
+   */
+  function startResendCooldown() {
+    resendCooldown = 30;
+    if (resendTimer) clearInterval(resendTimer);
+    resendTimer = setInterval(() => {
+      resendCooldown--;
+      if (resendCooldown <= 0 && resendTimer) {
+        clearInterval(resendTimer);
+        resendTimer = null;
+      }
+    }, 1000);
+  }
+
+  /**
+   * Start a countdown after receiving a rate-limit response from the
+   * server. Disables the code inputs and auto-clears the error when
+   * the countdown reaches zero.
+   *
+   * @param ms - The \`retryAfterMs\` value from the server response
+   */
+  function startRetryCountdown(ms: number) {
+    retryCountdown = Math.ceil(ms / 1000);
+    if (retryTimer) clearInterval(retryTimer);
+    retryTimer = setInterval(() => {
+      retryCountdown--;
+      if (retryCountdown <= 0) {
+        retryCountdown = 0;
+        error = null;
+        if (retryTimer) {
+          clearInterval(retryTimer);
+          retryTimer = null;
+        }
+      }
+    }, 1000);
+  }
+
+  // =============================================================================
+  //  Email Resend Handler
+  // =============================================================================
+
+  /**
+   * Resend the confirmation or verification email depending on
+   * which modal is currently visible. Respects the resend cooldown.
+   */
+  async function handleResendEmail() {
+    if (resendCooldown > 0) return;
+    startResendCooldown();
+    /* For setup confirmation → resend the signup email */
+    if (showConfirmationModal) {
+      const { resendConfirmationEmail } = await import('@prabhask5/stellar-engine');
+      await resendConfirmationEmail(email);
+    }
+    /* For device verification → resend the OTP email */
+    if (showDeviceVerificationModal) {
+      const info = await getSingleUserInfo();
+      if (info?.email) {
+        await sendDeviceVerification(info.email);
+      }
+    }
+  }
+
+  // =============================================================================
+  //  Digit Input Handlers — Shared across all PIN-code fields
+  // =============================================================================
+
+  /**
+   * Handle a single digit being typed into a PIN input box. Filters
+   * non-numeric characters, auto-advances focus, and triggers
+   * \`onComplete\` when the last digit is filled.
+   *
+   * @param digits    - The reactive digit array being edited
+   * @param index     - Which position in the array this input represents
+   * @param event     - The native \`input\` DOM event
+   * @param inputs    - Array of \`HTMLInputElement\` refs for focus management
+   * @param onComplete - Optional callback invoked when all digits are filled
+   */
+  function handleDigitInput(
+    digits: string[],
+    index: number,
+    event: Event,
+    inputs: HTMLInputElement[],
+    onComplete?: () => void
+  ) {
+    const input = event.target as HTMLInputElement;
+    const value = input.value.replace(/[^0-9]/g, '');
+
+    if (value.length > 0) {
+      digits[index] = value.charAt(value.length - 1);
+      input.value = digits[index];
+      /* Auto-focus the next input box */
+      if (index < digits.length - 1 && inputs[index + 1]) {
+        inputs[index + 1].focus();
+      }
+      /* Auto-submit when the last digit is entered (brief delay for UX) */
+      if (index === digits.length - 1 && onComplete && digits.every((d) => d !== '')) {
+        setTimeout(() => onComplete(), 300);
+      }
+    } else {
+      digits[index] = '';
+    }
+  }
+
+  /**
+   * Handle backspace in a PIN input — moves focus to the previous
+   * input when the current one is already empty.
+   *
+   * @param digits - The reactive digit array
+   * @param index  - Current position index
+   * @param event  - The native \`keydown\` event
+   * @param inputs - Array of \`HTMLInputElement\` refs
+   */
+  function handleDigitKeydown(
+    digits: string[],
+    index: number,
+    event: KeyboardEvent,
+    inputs: HTMLInputElement[]
+  ) {
+    if (event.key === 'Backspace') {
+      if (digits[index] === '' && index > 0 && inputs[index - 1]) {
+        inputs[index - 1].focus();
+        digits[index - 1] = '';
+      } else {
+        digits[index] = '';
+      }
+    }
+  }
+
+  /**
+   * Handle paste into a PIN input — distributes pasted digits across
+   * all input boxes and auto-submits if the full code was pasted.
+   *
+   * @param digits     - The reactive digit array
+   * @param event      - The native \`paste\` clipboard event
+   * @param inputs     - Array of \`HTMLInputElement\` refs
+   * @param onComplete - Optional callback invoked when all digits are filled
+   */
+  function handleDigitPaste(
+    digits: string[],
+    event: ClipboardEvent,
+    inputs: HTMLInputElement[],
+    onComplete?: () => void
+  ) {
+    event.preventDefault();
+    const pasted = (event.clipboardData?.getData('text') || '').replace(/[^0-9]/g, '');
+    for (let i = 0; i < digits.length && i < pasted.length; i++) {
+      digits[i] = pasted[i];
+      if (inputs[i]) inputs[i].value = pasted[i];
+    }
+    const focusIndex = Math.min(pasted.length, digits.length - 1);
+    if (inputs[focusIndex]) inputs[focusIndex].focus();
+    /* Auto-submit if the full code was pasted at once */
+    if (pasted.length >= digits.length && onComplete && digits.every((d) => d !== '')) {
+      onComplete();
+    }
+  }
+
+  // =============================================================================
+  //  Setup Mode — Step Navigation
+  // =============================================================================
+
+  /**
+   * Validate email and first name, then advance to the PIN-creation
+   * step (step 2). Shows an error if validation fails.
+   */
+  function goToCodeStep() {
+    if (!email.trim() || !/^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(email.trim())) {
+      error = 'Please enter a valid email address';
+      return;
+    }
+    if (!firstName.trim()) {
+      error = 'First name is required';
+      return;
+    }
+    error = null;
+    setupStep = 2;
+  }
+
+  /**
+   * Navigate back from step 2 (PIN creation) to step 1 (email/name).
+   */
+  function goBackToNameStep() {
+    setupStep = 1;
+    error = null;
+  }
+
+  /**
+   * Auto-focus the first confirm-code input when the primary code
+   * is fully entered.
+   */
+  function autoFocusConfirm() {
+    if (confirmInputs[0]) confirmInputs[0].focus();
+  }
+
+  /**
+   * Trigger setup submission when the confirm-code auto-completes.
+   */
+  function autoSubmitSetup() {
+    if (confirmDigits.every((d) => d !== '')) {
+      handleSetup();
+    }
+  }
+
+  /**
+   * Trigger unlock submission when the unlock-code auto-completes.
+   */
+  function autoSubmitUnlock() {
+    handleUnlock();
+  }
+
+  // =============================================================================
+  //  Setup Mode — Account Creation
+  // =============================================================================
+
+  /**
+   * Handle the full setup flow: validate the code matches its
+   * confirmation, call \`setupSingleUser\`, and handle the response
+   * (which may require email confirmation or succeed immediately).
+   */
+  async function handleSetup() {
+    if (loading) return;
+
+    error = null;
+
+    if (code.length !== 6) {
+      error = 'Please enter a 6-digit code';
+      return;
+    }
+
+    /* Verify code and confirmation match */
+    if (code !== confirmCode) {
+      error = 'Codes do not match';
+      shaking = true;
+      setTimeout(() => {
+        shaking = false;
+      }, 500);
+      /* Clear confirm digits and refocus the first confirm input */
+      confirmDigits = ['', '', '', '', '', ''];
+      if (confirmInputs[0]) confirmInputs[0].focus();
+      return;
+    }
+
+    loading = true;
+
+    try {
+      const result = await setupSingleUser(
+        code,
+        {
+          firstName: firstName.trim(),
+          lastName: lastName.trim()
+        },
+        email.trim()
+      );
+      if (result.error) {
+        error = result.error;
+        shaking = true;
+        setTimeout(() => {
+          shaking = false;
+        }, 500);
+        codeDigits = ['', '', '', '', '', ''];
+        confirmDigits = ['', '', '', '', '', ''];
+        if (codeInputs[0]) codeInputs[0].focus();
+        return;
+      }
+      if (result.confirmationRequired) {
+        /* Email confirmation needed → show the "check your email" modal */
+        showConfirmationModal = true;
+        startResendCooldown();
+        return;
+      }
+      /* No confirmation needed → go straight to the app */
+      await invalidateAll();
+      goto('/');
+    } catch (err: unknown) {
+      error = err instanceof Error ? err.message : 'Setup failed. Please try again.';
+      shaking = true;
+      setTimeout(() => {
+        shaking = false;
+      }, 500);
+      codeDigits = ['', '', '', '', '', ''];
+      confirmDigits = ['', '', '', '', '', ''];
+      if (codeInputs[0]) codeInputs[0].focus();
+    } finally {
+      loading = false;
+    }
+  }
+
+  // =============================================================================
+  //  Unlock Mode — PIN Entry for Returning Users
+  // =============================================================================
+
+  /**
+   * Attempt to unlock the local account with the entered 6-digit PIN.
+   * Handles rate-limiting, device verification requirements, and
+   * error feedback with shake animation.
+   */
+  async function handleUnlock() {
+    if (loading || retryCountdown > 0) return;
+
+    error = null;
+
+    if (unlockCode.length !== 6) {
+      error = 'Please enter your 6-digit code';
+      return;
+    }
+
+    loading = true;
+
+    try {
+      const result = await unlockSingleUser(unlockCode);
+      if (result.error) {
+        error = result.error;
+        if (result.retryAfterMs) {
+          startRetryCountdown(result.retryAfterMs);
+        }
+        shaking = true;
+        setTimeout(() => {
+          shaking = false;
+        }, 500);
+        unlockDigits = ['', '', '', '', '', ''];
+        return;
+      }
+      if (result.deviceVerificationRequired) {
+        /* Untrusted device → show verification modal + start polling */
+        maskedEmail = result.maskedEmail || '';
+        showDeviceVerificationModal = true;
+        startResendCooldown();
+        startVerificationPolling();
+        return;
+      }
+      /* Success → navigate to the redirect target */
+      await invalidateAll();
+      goto(redirectUrl);
+    } catch (err: unknown) {
+      error = err instanceof Error ? err.message : 'Incorrect code';
+      shaking = true;
+      setTimeout(() => {
+        shaking = false;
+      }, 500);
+      unlockDigits = ['', '', '', '', '', ''];
+    } finally {
+      loading = false;
+      if (error) {
+        await tick();
+        if (unlockInputs[0]) unlockInputs[0].focus();
+      }
+    }
+  }
+
+  // =============================================================================
+  //  Link Device Mode — Connect a New Device to an Existing Account
+  // =============================================================================
+
+  /**
+   * Trigger link submission when the link-code auto-completes.
+   */
+  function autoSubmitLink() {
+    if (linkDigits.every((d) => d !== '')) {
+      handleLink();
+    }
+  }
+
+  /**
+   * Attempt to link this device to the remote user account by
+   * submitting the PIN. Similar flow to unlock — may require device
+   * verification or trigger rate-limiting.
+   */
+  async function handleLink() {
+    if (linkLoading || !remoteUser || retryCountdown > 0) return;
+
+    error = null;
+
+    if (linkCode.length !== remoteUser.codeLength) {
+      error = \`Please enter a \${remoteUser.codeLength}-digit code\`;
+      return;
+    }
+
+    linkLoading = true;
+    try {
+      const result = await linkSingleUserDevice(remoteUser.email, linkCode);
+      if (result.error) {
+        error = result.error;
+        if (result.retryAfterMs) {
+          startRetryCountdown(result.retryAfterMs);
+        }
+        shaking = true;
+        setTimeout(() => {
+          shaking = false;
+        }, 500);
+        linkDigits = Array(remoteUser.codeLength).fill('');
+        return;
+      }
+      if (result.deviceVerificationRequired) {
+        maskedEmail = result.maskedEmail || '';
+        showDeviceVerificationModal = true;
+        startResendCooldown();
+        startVerificationPolling();
+        return;
+      }
+      /* Success → navigate to the redirect target */
+      await invalidateAll();
+      goto(redirectUrl);
+    } catch (err: unknown) {
+      error = err instanceof Error ? err.message : 'Incorrect code';
+      shaking = true;
+      setTimeout(() => {
+        shaking = false;
+      }, 500);
+      linkDigits = Array(remoteUser.codeLength).fill('');
+    } finally {
+      linkLoading = false;
+      if (error) {
+        await tick();
+        if (linkInputs[0]) linkInputs[0].focus();
+      }
+    }
+  }
+</script>
+
+<svelte:head>
+  <title>Login - ${opts.name}</title>
+</svelte:head>
+
+<!-- TODO: Add login page template (PIN inputs, setup wizard, device verification modal) -->
+`;
+}
+/**
+ * Generate the email confirmation page component that handles token
+ * verification and cross-tab broadcast.
+ *
+ * @returns The Svelte component source for `src/routes/confirm/+page.svelte`.
+ */
+function generateConfirmPage(opts) {
+    return `<!--
+  @fileoverview Email confirmation page — token verification, BroadcastChannel
+  relay, and close/redirect flow.
+
+  Supabase email links land here with \`?token_hash=...&type=...\` query
+  params. The page verifies the token, broadcasts the result to the
+  originating tab via BroadcastChannel, and either tells the user they
+  can close the tab or redirects them to the app root.
+-->
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { goto } from '$app/navigation';
+  import { page } from '$app/stores';
+  import { handleEmailConfirmation, broadcastAuthConfirmed } from '@prabhask5/stellar-engine/kit';
+
+  // ==========================================================================
+  //                                 STATE
+  // ==========================================================================
+
+  /** Current page state — drives which UI variant is rendered. */
+  let status: 'verifying' | 'success' | 'error' | 'redirecting' | 'can_close' = 'verifying';
+
+  /** Human-readable error message when verification fails. */
+  let errorMessage = '';
+
+  // ==========================================================================
+  //                              CONSTANTS
+  // ==========================================================================
+
+  /** BroadcastChannel name shared with the login page. */
+  const CHANNEL_NAME = '${opts.prefix}-auth-channel';
+
+  // ==========================================================================
+  //                              LIFECYCLE
+  // ==========================================================================
+
+  onMount(async () => {
+    /* ── Read Supabase callback params ── */
+    const tokenHash = $page.url.searchParams.get('token_hash');
+    const type = $page.url.searchParams.get('type');
+
+    /* ── Token present → verify it ── */
+    if (tokenHash && type) {
+      const result = await handleEmailConfirmation(
+        tokenHash,
+        type as 'signup' | 'email' | 'email_change' | 'magiclink'
+      );
+
+      if (!result.success) {
+        status = 'error';
+        errorMessage = result.error || 'Unknown error';
+        return;
+      }
+
+      status = 'success';
+      /* Brief pause so the user sees the success state */
+      await new Promise((resolve) => setTimeout(resolve, 800));
+    }
+
+    /* ── Notify the originating tab and decide next action ── */
+    const tabResult = await broadcastAuthConfirmed(CHANNEL_NAME, type || 'signup');
+    if (tabResult === 'can_close') {
+      status = 'can_close';
+    } else if (tabResult === 'no_broadcast') {
+      focusOrRedirect();
+    }
+  });
+
+  // ==========================================================================
+  //                              HELPERS
+  // ==========================================================================
+
+  /**
+   * Broadcast a confirmation event to any listening login tab, then
+   * attempt to close this browser tab. Falls back to a static
+   * "you can close this tab" message when \`window.close()\` is denied.
+   */
+  async function focusOrRedirect() {
+    status = 'redirecting';
+
+    const type = $page.url.searchParams.get('type') || 'signup';
+
+    const result = await broadcastAuthConfirmed(CHANNEL_NAME, type);
+
+    if (result === 'no_broadcast') {
+      /* BroadcastChannel unsupported — redirect to home directly */
+      goto('/', { replaceState: true });
+    } else {
+      /* 'can_close' — window.close() was blocked by browser */
+      setTimeout(() => {
+        status = 'can_close';
+      }, 200);
+    }
+  }
+</script>
+
+<svelte:head>
+  <title>Confirming... - ${opts.name}</title>
+</svelte:head>
 
 <!-- TODO: Add confirmation page template (verifying/success/error/can_close states) -->
 `;
@@ -1814,50 +3174,46 @@ export function load() {
  */
 function generateProtectedLayoutTs() {
     return `/**
- * @fileoverview Auth Guard — protected route group layout loader.
+ * @fileoverview Protected Layout Load Function — Auth Guard
  *
- * Redirects unauthenticated users to \`/login\`, preserving the intended
- * destination as a \`?redirect=\` query parameter so the login page can
- * navigate back after successful authentication.
+ * Runs on every navigation into the \`(protected)\` route group.
+ * Resolves the current authentication state via \`stellar-engine\` and
+ * redirects unauthenticated users to \`/login\` (preserving the intended
+ * destination as a \`?redirect=\` query parameter).
+ *
+ * On the server (SSR), returns a neutral "unauthenticated" payload so
+ * that the actual auth check happens exclusively in the browser where
+ * cookies / local storage are available.
  */
 
 import { redirect } from '@sveltejs/kit';
 import { browser } from '$app/environment';
-import { resolveAuthState } from '@prabhask5/stellar-engine/auth';
-import type { AuthMode, OfflineCredentials, Session } from '@prabhask5/stellar-engine/types';
+import { resolveProtectedLayout } from '@prabhask5/stellar-engine/kit';
+import type { ProtectedLayoutData } from '@prabhask5/stellar-engine/kit';
 import type { LayoutLoad } from './$types';
 
-/**
- * Data returned by the protected layout load function.
- */
-export interface ProtectedLayoutData {
-  /** Active Supabase session, or \`null\` when offline. */
-  session: Session | null;
-  /** Current authentication mode (\`'online'\`, \`'offline'\`, or \`'none'\`). */
-  authMode: AuthMode;
-  /** Cached offline credentials when auth mode is offline. */
-  offlineProfile: OfflineCredentials | null;
-}
+export type { ProtectedLayoutData };
 
 /**
- * Enforce authentication — redirect to login if the user has no session.
+ * SvelteKit universal \`load\` function for the \`(protected)\` layout.
  *
- * @param params - SvelteKit load params (provides the current URL).
- * @returns Protected layout data with guaranteed auth state.
+ * - **Browser**: resolves the auth state; redirects to \`/login\` if \`authMode\` is \`'none'\`.
+ * - **Server**: short-circuits with a neutral payload (auth is client-side only).
+ *
+ * @param url — The current page URL, used to build the redirect target.
+ * @returns Resolved \`ProtectedLayoutData\` for downstream pages and layouts.
  */
 export const load: LayoutLoad = async ({ url }): Promise<ProtectedLayoutData> => {
   if (browser) {
-    const result = await resolveAuthState();
-    if (result.authMode === 'none') {
-      const returnUrl = url.pathname + url.search;
-      const loginUrl =
-        returnUrl && returnUrl !== '/'
-          ? \`/login?redirect=\${encodeURIComponent(returnUrl)}\`
-          : '/login';
-      throw redirect(302, loginUrl);
+    const { data, redirectUrl } = await resolveProtectedLayout(url);
+
+    if (redirectUrl) {
+      throw redirect(302, redirectUrl);
     }
-    return result;
+
+    return data;
   }
+
   /* SSR fallback — no auth info available on the server */
   return { session: null, authMode: 'none', offlineProfile: null };
 };
@@ -1898,6 +3254,7 @@ function generateProtectedLayoutSvelte() {
   // TODO: Add conditional page backgrounds or other protected-area chrome
 </script>
 
+<!-- Render child route content -->
 {@render children?.()}
 `;
 }
@@ -1907,9 +3264,9 @@ function generateProtectedLayoutSvelte() {
  *
  * @returns The Svelte component source for `src/routes/(protected)/profile/+page.svelte`.
  */
-function generateProfilePage() {
+function generateProfilePage(opts) {
     return `<!--
-  @fileoverview Profile & administration page.
+  @fileoverview Profile & settings page.
 
   Capabilities:
     - View / edit display name and avatar
@@ -1920,9 +3277,9 @@ function generateProfilePage() {
     - Reset local database (destructive — requires confirmation)
 -->
 <script lang="ts">
-  // ==========================================================================
-  //                                IMPORTS
-  // ==========================================================================
+  // =============================================================================
+  //                               IMPORTS
+  // =============================================================================
 
   import { goto } from '$app/navigation';
   import {
@@ -1930,10 +3287,10 @@ function generateProfilePage() {
     updateSingleUserProfile,
     getSingleUserInfo,
     changeSingleUserEmail,
-    completeSingleUserEmailChange
+    completeSingleUserEmailChange,
+    resolveUserId,
+    resolveAvatarInitial
   } from '@prabhask5/stellar-engine/auth';
-  // TODO: Import resolveFirstName, resolveUserId, resolveAvatarInitial
-  // from '@prabhask5/stellar-engine/auth' for display name and avatar logic
   import { authState } from '@prabhask5/stellar-engine/stores';
   import { isDebugMode, setDebugMode } from '@prabhask5/stellar-engine/utils';
   import {
@@ -1942,14 +3299,613 @@ function generateProfilePage() {
     removeTrustedDevice,
     getCurrentDeviceId
   } from '@prabhask5/stellar-engine';
+  import type { TrustedDevice } from '@prabhask5/stellar-engine';
+  import { onMount } from 'svelte';
 
-  // ==========================================================================
-  //                           COMPONENT STATE
-  // ==========================================================================
+  // =============================================================================
+  //                         COMPONENT STATE
+  // =============================================================================
+
+  /* ── Profile form fields ──── */
+  let firstName = $state('');
+  let lastName = $state('');
+
+  /* ── Gate (6-digit code) change — digit-array approach ──── */
+  let oldCodeDigits = $state(['', '', '', '', '', '']);
+  let newCodeDigits = $state(['', '', '', '', '', '']);
+  let confirmCodeDigits = $state(['', '', '', '', '', '']);
+
+  /** Concatenated old code string → derived from individual digit inputs */
+  const oldCode = $derived(oldCodeDigits.join(''));
+  /** Concatenated new code string → derived from individual digit inputs */
+  const newCode = $derived(newCodeDigits.join(''));
+  /** Concatenated confirm code string — must match \`newCode\` */
+  const confirmNewCode = $derived(confirmCodeDigits.join(''));
+
+  /* ── Input element refs for auto-focus advancement ──── */
+  let oldCodeInputs: HTMLInputElement[] = $state([]);
+  let newCodeInputs: HTMLInputElement[] = $state([]);
+  let confirmCodeInputs: HTMLInputElement[] = $state([]);
+
+  /* ── Email change fields ──── */
+  let currentEmail = $state('');
+  let newEmail = $state('');
+  let emailLoading = $state(false);
+  let emailError = $state<string | null>(null);
+  let emailSuccess = $state<string | null>(null);
+  /** Whether the email confirmation modal overlay is visible */
+  let showEmailConfirmationModal = $state(false);
+  /** Seconds remaining before the user can re-send the confirmation email */
+  let emailResendCooldown = $state(0);
+
+  /* ── General UI / feedback state ──── */
+  let profileLoading = $state(false);
+  let codeLoading = $state(false);
+  let profileError = $state<string | null>(null);
+  let profileSuccess = $state<string | null>(null);
+  let codeError = $state<string | null>(null);
+  let codeSuccess = $state<string | null>(null);
+  let debugMode = $state(isDebugMode());
+  let resetting = $state(false);
+
+  /* ── Debug tools loading flags ──── */
+  let forceSyncing = $state(false);
+  let triggeringSyncManual = $state(false);
+  let resettingCursor = $state(false);
+  let checkingConnection = $state(false);
+  let viewingTombstones = $state(false);
+  let cleaningTombstones = $state(false);
+
+  /* ── Trusted devices ──── */
+  let trustedDevices = $state<TrustedDevice[]>([]);
+  let currentDeviceId = $state('');
+  let devicesLoading = $state(true);
+  /** ID of the device currently being removed — shows spinner on that row */
+  let removingDeviceId = $state<string | null>(null);
+
+  // =============================================================================
+  //                           LIFECYCLE
+  // =============================================================================
+
+  /** Populate form fields from the engine and load trusted devices on mount. */
+  onMount(async () => {
+    const info = await getSingleUserInfo();
+    if (info) {
+      firstName = (info.profile.firstName as string) || '';
+      lastName = (info.profile.lastName as string) || '';
+      currentEmail = info.email || '';
+    }
+
+    // Load trusted devices
+    currentDeviceId = getCurrentDeviceId();
+    try {
+      const userId = resolveUserId($authState?.session, $authState?.offlineProfile);
+      if (userId) {
+        trustedDevices = await getTrustedDevices(userId);
+      }
+    } catch {
+      // Ignore errors loading devices
+    }
+    devicesLoading = false;
+  });
+
+  // =============================================================================
+  //                     DIGIT INPUT HELPERS
+  // =============================================================================
+
+  /**
+   * Handle single-digit input in a code field.
+   * Auto-advances focus to the next input when a digit is entered.
+   * @param digits  - Reactive digit array to mutate
+   * @param index   - Position in the 6-digit code (0–5)
+   * @param event   - Native input event
+   * @param inputs  - Array of \`<input>\` refs for focus management
+   */
+  function handleDigitInput(
+    digits: string[],
+    index: number,
+    event: Event,
+    inputs: HTMLInputElement[]
+  ) {
+    const input = event.target as HTMLInputElement;
+    const value = input.value.replace(/[^0-9]/g, '');
+    if (value.length > 0) {
+      digits[index] = value.charAt(value.length - 1);
+      input.value = digits[index];
+      if (index < 5 && inputs[index + 1]) {
+        inputs[index + 1].focus();
+      }
+    } else {
+      digits[index] = '';
+    }
+  }
+
+  /**
+   * Handle Backspace in a digit field — moves focus backward when the current
+   * digit is already empty.
+   * @param digits  - Reactive digit array to mutate
+   * @param index   - Position in the 6-digit code (0–5)
+   * @param event   - Native keyboard event
+   * @param inputs  - Array of \`<input>\` refs for focus management
+   */
+  function handleDigitKeydown(
+    digits: string[],
+    index: number,
+    event: KeyboardEvent,
+    inputs: HTMLInputElement[]
+  ) {
+    if (event.key === 'Backspace') {
+      if (digits[index] === '' && index > 0 && inputs[index - 1]) {
+        inputs[index - 1].focus();
+        digits[index - 1] = '';
+      } else {
+        digits[index] = '';
+      }
+    }
+  }
+
+  /**
+   * Handle paste into a digit field — distributes pasted digits across all 6 inputs.
+   * @param digits  - Reactive digit array to mutate
+   * @param event   - Native clipboard event
+   * @param inputs  - Array of \`<input>\` refs for focus management
+   */
+  function handleDigitPaste(digits: string[], event: ClipboardEvent, inputs: HTMLInputElement[]) {
+    event.preventDefault();
+    const pasted = (event.clipboardData?.getData('text') || '').replace(/[^0-9]/g, '');
+    for (let i = 0; i < 6 && i < pasted.length; i++) {
+      digits[i] = pasted[i];
+      if (inputs[i]) inputs[i].value = pasted[i];
+    }
+    const focusIndex = Math.min(pasted.length, 5);
+    if (inputs[focusIndex]) inputs[focusIndex].focus();
+  }
+
+  // =============================================================================
+  //                      FORM SUBMISSION HANDLERS
+  // =============================================================================
+
+  /**
+   * Submit profile name changes to the engine and update the auth store
+   * so the navbar reflects changes immediately.
+   * @param e - Form submit event
+   */
+  async function handleProfileSubmit(e: Event) {
+    e.preventDefault();
+    profileLoading = true;
+    profileError = null;
+    profileSuccess = null;
+
+    try {
+      await updateSingleUserProfile({
+        firstName: firstName.trim(),
+        lastName: lastName.trim()
+      });
+      // Update auth state to immediately reflect changes in navbar
+      authState.updateUserProfile({ first_name: firstName.trim(), last_name: lastName.trim() });
+      profileSuccess = 'Profile updated successfully';
+      setTimeout(() => (profileSuccess = null), 3000);
+    } catch (err: unknown) {
+      profileError = err instanceof Error ? err.message : 'Failed to update profile';
+    }
+
+    profileLoading = false;
+  }
+
+  /**
+   * Validate and submit a 6-digit gate code change.
+   * Resets all digit arrays on success.
+   * @param e - Form submit event
+   */
+  async function handleCodeSubmit(e: Event) {
+    e.preventDefault();
+
+    if (oldCode.length !== 6) {
+      codeError = 'Please enter your current 6-digit code';
+      return;
+    }
+
+    if (newCode.length !== 6) {
+      codeError = 'Please enter a new 6-digit code';
+      return;
+    }
+
+    if (newCode !== confirmNewCode) {
+      codeError = 'New codes do not match';
+      return;
+    }
+
+    codeLoading = true;
+    codeError = null;
+    codeSuccess = null;
+
+    try {
+      await changeSingleUserGate(oldCode, newCode);
+      codeSuccess = 'Code changed successfully';
+      oldCodeDigits = ['', '', '', '', '', ''];
+      newCodeDigits = ['', '', '', '', '', ''];
+      confirmCodeDigits = ['', '', '', '', '', ''];
+      setTimeout(() => (codeSuccess = null), 3000);
+    } catch (err: unknown) {
+      codeError = err instanceof Error ? err.message : 'Failed to change code';
+    }
+
+    codeLoading = false;
+  }
+
+  // =============================================================================
+  //                      EMAIL CHANGE FLOW
+  // =============================================================================
+
+  /**
+   * Initiate an email change — sends a confirmation link to the new address.
+   * Opens the confirmation modal and starts listening for the cross-tab
+   * \`BroadcastChannel\` auth event.
+   * @param e - Form submit event
+   */
+  async function handleEmailSubmit(e: Event) {
+    e.preventDefault();
+    emailError = null;
+    emailSuccess = null;
+
+    if (!newEmail.trim()) {
+      emailError = 'Please enter a new email address';
+      return;
+    }
+
+    if (newEmail.trim() === currentEmail) {
+      emailError = 'New email is the same as your current email';
+      return;
+    }
+
+    emailLoading = true;
+
+    try {
+      const result = await changeSingleUserEmail(newEmail.trim());
+      if (result.error) {
+        emailError = result.error;
+      } else if (result.confirmationRequired) {
+        showEmailConfirmationModal = true;
+        startResendCooldown();
+        listenForEmailConfirmation();
+      }
+    } catch (err: unknown) {
+      emailError = err instanceof Error ? err.message : 'Failed to change email';
+    }
+
+    emailLoading = false;
+  }
+
+  /** Start a 30-second countdown preventing repeated confirmation emails. */
+  function startResendCooldown() {
+    emailResendCooldown = 30;
+    const interval = setInterval(() => {
+      emailResendCooldown--;
+      if (emailResendCooldown <= 0) clearInterval(interval);
+    }, 1000);
+  }
+
+  /** Re-send the email change confirmation (guarded by cooldown). */
+  async function handleResendEmailChange() {
+    if (emailResendCooldown > 0) return;
+    try {
+      await changeSingleUserEmail(newEmail.trim());
+      startResendCooldown();
+    } catch {
+      // Ignore resend errors
+    }
+  }
 
-  // TODO: Add profile page state (form fields, device management, debug tools)
+  /**
+   * Listen on a \`BroadcastChannel\` for the confirmation tab to signal
+   * that the user clicked the email-change link. Once received, complete
+   * the email change server-side and update local state.
+   */
+  function listenForEmailConfirmation() {
+    if (!('BroadcastChannel' in window)) return;
+    const channel = new BroadcastChannel('stellar-auth-channel');
+    channel.onmessage = async (event) => {
+      if (
+        event.data?.type === 'AUTH_CONFIRMED' &&
+        event.data?.verificationType === 'email_change'
+      ) {
+        // Bring this tab to the foreground before the confirm tab closes
+        window.focus();
+        const result = await completeSingleUserEmailChange();
+        if (!result.error && result.newEmail) {
+          currentEmail = result.newEmail;
+          emailSuccess = 'Email changed successfully';
+          newEmail = '';
+          setTimeout(() => (emailSuccess = null), 5000);
+        } else {
+          emailError = result.error || 'Failed to complete email change';
+        }
+        showEmailConfirmationModal = false;
+        channel.close();
+      }
+    };
+  }
+
+  /** Close the email confirmation modal without completing the change. */
+  function dismissEmailModal() {
+    showEmailConfirmationModal = false;
+  }
+
+  // =============================================================================
+  //                     ADMINISTRATION HANDLERS
+  // =============================================================================
+
+  /** Toggle debug mode on/off — requires a page refresh to take full effect. */
+  function toggleDebugMode() {
+    debugMode = !debugMode;
+    setDebugMode(debugMode);
+  }
+
+  /** Navigate back to the main tasks view. */
+  function goBack() {
+    goto('/tasks');
+  }
+
+  /**
+   * Delete and recreate the local IndexedDB, then reload the page.
+   * Session is preserved in localStorage so the app will re-hydrate.
+   */
+  async function handleResetDatabase() {
+    if (
+      !confirm(
+        'This will delete all local data and reload. Your data will be re-synced from the server. Continue?'
+      )
+    ) {
+      return;
+    }
+    resetting = true;
+    try {
+      await resetDatabase();
+      // Reload the page — session is preserved in localStorage, so the app
+      // will re-create the DB, fetch config from Supabase, and re-hydrate.
+      window.location.reload();
+    } catch (err) {
+      alert('Reset failed: ' + (err instanceof Error ? err.message : 'Unknown error'));
+      resetting = false;
+    }
+  }
+
+  /**
+   * Remove a trusted device by ID and update the local list.
+   * @param id - Database ID of the trusted device row
+   */
+  async function handleRemoveDevice(id: string) {
+    removingDeviceId = id;
+    try {
+      await removeTrustedDevice(id);
+      trustedDevices = trustedDevices.filter((d) => d.id !== id);
+    } catch {
+      // Ignore errors
+    }
+    removingDeviceId = null;
+  }
+
+  // =============================================================================
+  //                     DEBUG TOOL HANDLERS
+  // =============================================================================
+
+  /**
+   * Cast \`window\` to an untyped record for accessing runtime-injected
+   * debug helpers (e.g., \`__${opts.prefix}Sync\`, \`__${opts.prefix}SyncStats\`).
+   * @returns The global \`window\` as a loose \`Record\`
+   */
+  function getDebugWindow(): Record<string, unknown> {
+    return window as unknown as Record<string, unknown>;
+  }
+
+  /** Resets the sync cursor and re-downloads all data from Supabase. */
+  async function handleForceFullSync() {
+    if (
+      !confirm(
+        'This will reset the sync cursor and re-download all data from the server. Continue?'
+      )
+    )
+      return;
+    forceSyncing = true;
+    try {
+      const fn = getDebugWindow().__${opts.prefix}Sync as
+        | { forceFullSync: () => Promise<void> }
+        | undefined;
+      if (fn?.forceFullSync) {
+        await fn.forceFullSync();
+        alert('Force full sync complete.');
+      } else {
+        alert('Debug mode must be enabled and the page refreshed to use this tool.');
+      }
+    } catch (err) {
+      alert('Force full sync failed: ' + (err instanceof Error ? err.message : 'Unknown error'));
+    }
+    forceSyncing = false;
+  }
+
+  /** Manually trigger a single push/pull sync cycle. */
+  async function handleTriggerSync() {
+    triggeringSyncManual = true;
+    try {
+      const fn = getDebugWindow().__${opts.prefix}Sync as { sync: () => Promise<void> } | undefined;
+      if (fn?.sync) {
+        await fn.sync();
+        alert('Sync cycle complete.');
+      } else {
+        alert('Debug mode must be enabled and the page refreshed to use this tool.');
+      }
+    } catch (err) {
+      alert('Sync failed: ' + (err instanceof Error ? err.message : 'Unknown error'));
+    }
+    triggeringSyncManual = false;
+  }
+
+  /** Reset the sync cursor so the next cycle pulls all remote data. */
+  async function handleResetSyncCursor() {
+    resettingCursor = true;
+    try {
+      const fn = getDebugWindow().__${opts.prefix}Sync as
+        | { resetSyncCursor: () => Promise<void> }
+        | undefined;
+      if (fn?.resetSyncCursor) {
+        await fn.resetSyncCursor();
+        alert('Sync cursor reset. The next sync will pull all data.');
+      } else {
+        alert('Debug mode must be enabled and the page refreshed to use this tool.');
+      }
+    } catch (err) {
+      alert('Reset cursor failed: ' + (err instanceof Error ? err.message : 'Unknown error'));
+    }
+    resettingCursor = false;
+  }
+
+  /** Test connectivity to Supabase and show the result in an alert. */
+  async function handleCheckConnection() {
+    checkingConnection = true;
+    try {
+      const fn = getDebugWindow().__${opts.prefix}Sync as
+        | {
+            checkConnection: () => Promise<{
+              connected: boolean;
+              error?: string;
+              records?: number;
+            }>;
+          }
+        | undefined;
+      if (fn?.checkConnection) {
+        const result = await fn.checkConnection();
+        if (result.connected) {
+          alert('Connection OK. Supabase is reachable.');
+        } else {
+          alert('Connection failed: ' + (result.error || 'Unknown error'));
+        }
+      } else {
+        alert('Debug mode must be enabled and the page refreshed to use this tool.');
+      }
+    } catch (err) {
+      alert('Connection check failed: ' + (err instanceof Error ? err.message : 'Unknown error'));
+    }
+    checkingConnection = false;
+  }
+
+  /** Display current sync cursor and pending operations count in an alert. */
+  function handleGetSyncStatus() {
+    const fn = getDebugWindow().__${opts.prefix}Sync as
+      | { getStatus: () => { cursor: unknown; pendingOps: Promise<number> } }
+      | undefined;
+    if (fn?.getStatus) {
+      const status = fn.getStatus();
+      const cursorDisplay =
+        typeof status.cursor === 'object'
+          ? JSON.stringify(status.cursor)
+          : String(status.cursor || 'None');
+      status.pendingOps.then((count: number) => {
+        alert(\`Sync Status:\n\nCursor: \${cursorDisplay}\nPending operations: \${count}\`);
+      });
+    } else {
+      alert('Debug mode must be enabled and the page refreshed to use this tool.');
+    }
+  }
+
+  /** Show the realtime WebSocket connection state and health. */
+  function handleRealtimeStatus() {
+    const fn = getDebugWindow().__${opts.prefix}Sync as
+      | { realtimeStatus: () => { state: string; healthy: boolean } }
+      | undefined;
+    if (fn?.realtimeStatus) {
+      const status = fn.realtimeStatus();
+      alert(
+        \`Realtime Status:\n\nState: \${status.state}\nHealthy: \${status.healthy ? 'Yes' : 'No'}\`
+      );
+    } else {
+      alert('Debug mode must be enabled and the page refreshed to use this tool.');
+    }
+  }
+
+  /** Display sync cycle stats in an alert; full details logged to console. */
+  function handleViewSyncStats() {
+    const fn = getDebugWindow().__${opts.prefix}SyncStats as
+      | (() => { totalSyncCycles: number; recentMinute: number; recent: unknown[] })
+      | undefined;
+    if (fn) {
+      const stats = fn();
+      alert(
+        \`Sync Stats:\n\nTotal cycles: \${stats.totalSyncCycles}\nCycles in last minute: \${stats.recentMinute}\nRecent cycles logged to console.\`
+      );
+    } else {
+      alert('Debug mode must be enabled and the page refreshed to use this tool.');
+    }
+  }
+
+  /** Display data-transfer / egress stats; per-table breakdown in console. */
+  function handleViewEgress() {
+    const fn = getDebugWindow().__${opts.prefix}Egress as
+      | (() => { totalFormatted: string; totalRecords: number; sessionStart: string })
+      | undefined;
+    if (fn) {
+      const stats = fn();
+      alert(
+        \`Egress Stats:\n\nTotal data transferred: \${stats.totalFormatted}\nTotal records: \${stats.totalRecords}\nSession started: \${new Date(stats.sessionStart).toLocaleString()}\n\nFull breakdown logged to console.\`
+      );
+    } else {
+      alert('Debug mode must be enabled and the page refreshed to use this tool.');
+    }
+  }
+
+  /** Log soft-deleted record counts per table to the browser console. */
+  async function handleViewTombstones() {
+    viewingTombstones = true;
+    try {
+      const fn = getDebugWindow().__${opts.prefix}Tombstones as
+        | ((opts?: { cleanup?: boolean; force?: boolean }) => Promise<void>)
+        | undefined;
+      if (fn) {
+        await fn();
+        alert('Tombstone details logged to console. Open DevTools to view.');
+      } else {
+        alert('Debug mode must be enabled and the page refreshed to use this tool.');
+      }
+    } catch (err) {
+      alert('View tombstones failed: ' + (err instanceof Error ? err.message : 'Unknown error'));
+    }
+    viewingTombstones = false;
+  }
+
+  /** Permanently remove old soft-deleted records from local + remote DBs. */
+  async function handleCleanupTombstones() {
+    if (
+      !confirm(
+        'This will permanently remove old soft-deleted records from local and server databases. Continue?'
+      )
+    )
+      return;
+    cleaningTombstones = true;
+    try {
+      const fn = getDebugWindow().__${opts.prefix}Tombstones as
+        | ((opts?: { cleanup?: boolean; force?: boolean }) => Promise<void>)
+        | undefined;
+      if (fn) {
+        await fn({ cleanup: true });
+        alert('Tombstone cleanup complete. Details logged to console.');
+      } else {
+        alert('Debug mode must be enabled and the page refreshed to use this tool.');
+      }
+    } catch (err) {
+      alert('Tombstone cleanup failed: ' + (err instanceof Error ? err.message : 'Unknown error'));
+    }
+    cleaningTombstones = false;
+  }
+
+  /** Dispatch a custom event that the app shell listens for to sign out on mobile. */
+  function handleMobileSignOut() {
+    window.dispatchEvent(new CustomEvent('${opts.prefix}:signout'));
+  }
 </script>
 
+<svelte:head>
+  <title>Profile - ${opts.name}</title>
+</svelte:head>
+
 <!-- TODO: Add profile page template (forms, cards, device list, debug tools) -->
 `;
 }
@@ -2079,38 +4035,102 @@ export type { SyncStatus, AuthMode, OfflineCredentials } from '@prabhask5/stella
 `;
 }
 // =============================================================================
+//                           COMMAND ROUTING
+// =============================================================================
+/**
+ * Available CLI commands. Add new entries here to register additional commands.
+ */
+const COMMANDS = [
+    {
+        name: 'install pwa',
+        usage: 'stellar-engine install pwa',
+        description: 'Scaffold a complete offline-first SvelteKit PWA project'
+    }
+];
+/**
+ * Print the help screen listing all available commands.
+ */
+function printHelp() {
+    console.log();
+    console.log(doubleBoxWithHeader([`          ${bold('\u2726 stellar-engine CLI \u2726')}            `], ['Available commands:                              ']));
+    console.log();
+    for (const cmd of COMMANDS) {
+        console.log(`  ${cyan(cmd.usage)}`);
+        console.log(`  ${dim(cmd.description)}`);
+        console.log();
+    }
+    console.log(`  Run a command to get started.\n`);
+}
+/**
+ * Route CLI arguments to the appropriate command handler.
+ * Prints help and exits if the command is not recognised.
+ */
+function routeCommand() {
+    const args = process.argv.slice(2);
+    const command = args.slice(0, 2).join(' ');
+    if (command === 'install pwa') {
+        main().catch((err) => {
+            console.error('Error:', err);
+            process.exit(1);
+        });
+        return;
+    }
+    /* Unrecognised command or no args — show help */
+    printHelp();
+    process.exit(args.length === 0 ? 0 : 1);
+}
+// =============================================================================
 //                              MAIN FUNCTION
 // =============================================================================
+/**
+ * Write a group of files quietly and return the count written.
+ *
+ * @param entries - Array of `[relativePath, content]` pairs.
+ * @param cwd - The current working directory.
+ * @param createdFiles - Accumulator for newly-created file paths.
+ * @param skippedFiles - Accumulator for skipped file paths.
+ * @returns The number of files in the group.
+ */
+function writeGroup(entries, cwd, createdFiles, skippedFiles) {
+    for (const [rel, content] of entries) {
+        writeIfMissing(join(cwd, rel), content, createdFiles, skippedFiles, true);
+    }
+    return entries.length;
+}
 /**
  * Main entry point for the CLI scaffolding tool.
  *
  * **Execution flow:**
- *   1. Parse CLI arguments into {@link InstallOptions}.
+ *   1. Run interactive walkthrough to collect {@link InstallOptions}.
  *   2. Write `package.json` (if missing).
  *   3. Run `npm install` to fetch dependencies.
- *   4. Write all template files (config, routes, components, assets, docs).
+ *   4. Write all template files by category with animated progress.
  *   5. Initialise Husky and write the pre-commit hook.
- *   6. Print a summary of created/skipped files and next steps.
+ *   6. Print a styled summary of created/skipped files and next steps.
  *
  * @returns A promise that resolves when scaffolding is complete.
  *
  * @throws {Error} If `npm install` or `npx husky init` fails.
  */
 async function main() {
-    const opts = parseArgs(process.argv);
+    const opts = await runInteractiveSetup();
     const cwd = process.cwd();
-    console.log(`\n\u2728 stellar-engine install pwa\n   Creating ${opts.name}...\n`);
     const createdFiles = [];
     const skippedFiles = [];
     // 1. Write package.json
-    writeIfMissing(join(cwd, 'package.json'), generatePackageJson(opts), createdFiles, skippedFiles);
+    let sp = createSpinner('Writing package.json');
+    writeIfMissing(join(cwd, 'package.json'), generatePackageJson(opts), createdFiles, skippedFiles, true);
+    sp.succeed('Writing package.json');
     // 2. Run npm install
-    console.log('Installing dependencies...');
+    sp = createSpinner('Installing dependencies...');
+    sp.stop();
+    console.log(`  ${cyan(SPINNER_FRAMES[0])} Installing dependencies...\n`);
     execSync('npm install', { stdio: 'inherit', cwd });
-    // 3. Write all template files
+    console.log(`\n  ${green('\u2713')} Installing dependencies`);
+    // 3. Write all template files by category
     const firstLetter = opts.shortName.charAt(0).toUpperCase();
-    const files = [
-        // Config files
+    /* ── Config files ── */
+    const configFiles = [
         ['vite.config.ts', generateViteConfig(opts)],
         ['tsconfig.json', generateTsconfig()],
         ['svelte.config.js', generateSvelteConfig(opts)],
@@ -2118,15 +4138,24 @@ async function main() {
         ['.prettierrc', generatePrettierrc()],
         ['.prettierignore', generatePrettierignore()],
         ['knip.json', generateKnipJson()],
-        ['.gitignore', generateGitignore()],
-        // Documentation
+        ['.gitignore', generateGitignore()]
+    ];
+    sp = createSpinner('Config files');
+    const configCount = writeGroup(configFiles, cwd, createdFiles, skippedFiles);
+    sp.succeed(`Config files               ${dim(`${configCount} files`)}`);
+    /* ── Documentation ── */
+    const docFiles = [
         ['README.md', generateReadme(opts)],
         ['ARCHITECTURE.md', generateArchitecture(opts)],
-        ['FRAMEWORKS.md', generateFrameworks()],
-        // Static assets
+        ['FRAMEWORKS.md', generateFrameworks()]
+    ];
+    sp = createSpinner('Documentation');
+    const docCount = writeGroup(docFiles, cwd, createdFiles, skippedFiles);
+    sp.succeed(`Documentation              ${dim(`${docCount} files`)}`);
+    /* ── Static assets ── */
+    const staticFiles = [
         ['static/manifest.json', generateManifest(opts)],
         ['static/offline.html', generateOfflineHtml(opts)],
-        // Placeholder icons
         ['static/icons/app.svg', generatePlaceholderSvg('#6c5ce7', firstLetter)],
         ['static/icons/app-dark.svg', generatePlaceholderSvg('#1a1a2e', firstLetter)],
         ['static/icons/maskable.svg', generatePlaceholderSvg('#6c5ce7', firstLetter)],
@@ -2134,64 +4163,75 @@ async function main() {
         ['static/icons/monochrome.svg', generateMonochromeSvg(firstLetter)],
         ['static/icons/splash.svg', generateSplashSvg(opts.shortName)],
         ['static/icons/apple-touch.svg', generatePlaceholderSvg('#6c5ce7', firstLetter)],
-        // Email placeholders
         ['static/change-email.html', generateEmailPlaceholder('Change Email')],
         ['static/device-verification-email.html', generateEmailPlaceholder('Device Verification')],
         ['static/signup-email.html', generateEmailPlaceholder('Signup Email')],
-        // Supabase schema
-        ['supabase-schema.sql', generateSupabaseSchema(opts)],
-        // Source files
+        ['supabase-schema.sql', generateSupabaseSchema(opts)]
+    ];
+    sp = createSpinner('Static assets');
+    const staticCount = writeGroup(staticFiles, cwd, createdFiles, skippedFiles);
+    sp.succeed(`Static assets             ${dim(`${staticCount} files`)}`);
+    /* ── Source files ── */
+    const sourceFiles = [
         ['src/app.html', generateAppHtml(opts)],
-        ['src/app.d.ts', generateAppDts(opts)],
-        // Route files
+        ['src/app.d.ts', generateAppDts(opts)]
+    ];
+    sp = createSpinner('Source files');
+    const sourceCount = writeGroup(sourceFiles, cwd, createdFiles, skippedFiles);
+    sp.succeed(`Source files               ${dim(`${sourceCount} files`)}`);
+    /* ── Route files ── */
+    const routeFiles = [
         ['src/routes/+layout.ts', generateRootLayoutTs(opts)],
-        ['src/routes/+layout.svelte', generateRootLayoutSvelte()],
-        ['src/routes/+page.svelte', generateHomePage()],
-        ['src/routes/+error.svelte', generateErrorPage()],
+        ['src/routes/+layout.svelte', generateRootLayoutSvelte(opts)],
+        ['src/routes/+page.svelte', generateHomePage(opts)],
+        ['src/routes/+error.svelte', generateErrorPage(opts)],
         ['src/routes/setup/+page.ts', generateSetupPageTs()],
-        ['src/routes/setup/+page.svelte', generateSetupPageSvelte()],
-        ['src/routes/policy/+page.svelte', generatePolicyPage()],
-        ['src/routes/login/+page.svelte', generateLoginPage()],
-        ['src/routes/confirm/+page.svelte', generateConfirmPage()],
+        ['src/routes/setup/+page.svelte', generateSetupPageSvelte(opts)],
+        ['src/routes/policy/+page.svelte', generatePolicyPage(opts)],
+        ['src/routes/login/+page.svelte', generateLoginPage(opts)],
+        ['src/routes/confirm/+page.svelte', generateConfirmPage(opts)],
         ['src/routes/api/config/+server.ts', generateConfigServer()],
         ['src/routes/api/setup/deploy/+server.ts', generateDeployServer()],
         ['src/routes/api/setup/validate/+server.ts', generateValidateServer()],
         ['src/routes/[...catchall]/+page.ts', generateCatchallPage()],
         ['src/routes/(protected)/+layout.ts', generateProtectedLayoutTs()],
         ['src/routes/(protected)/+layout.svelte', generateProtectedLayoutSvelte()],
-        ['src/routes/(protected)/profile/+page.svelte', generateProfilePage()],
+        ['src/routes/(protected)/profile/+page.svelte', generateProfilePage(opts)]
+    ];
+    sp = createSpinner('Route files');
+    const routeCount = writeGroup(routeFiles, cwd, createdFiles, skippedFiles);
+    sp.succeed(`Route files               ${dim(`${routeCount} files`)}`);
+    /* ── Library & components ── */
+    const libFiles = [
         ['src/lib/types.ts', generateAppTypes()],
-        // Component files
         ['src/lib/components/UpdatePrompt.svelte', generateUpdatePromptComponent()]
     ];
-    for (const [relativePath, content] of files) {
-        writeIfMissing(join(cwd, relativePath), content, createdFiles, skippedFiles);
-    }
+    sp = createSpinner('Library & components');
+    const libCount = writeGroup(libFiles, cwd, createdFiles, skippedFiles);
+    sp.succeed(`Library & components       ${dim(`${libCount} files`)}`);
     // 4. Set up husky
-    console.log('Setting up husky...');
-    execSync('npx husky init', { stdio: 'inherit', cwd });
-    /* Overwrite the default pre-commit (husky init creates one with "npm test") */
+    sp = createSpinner('Git hooks');
+    execSync('npx husky init', { stdio: 'pipe', cwd });
     const preCommitPath = join(cwd, '.husky/pre-commit');
     writeFileSync(preCommitPath, generateHuskyPreCommit(), 'utf-8');
     createdFiles.push('.husky/pre-commit');
-    console.log('  [write] .husky/pre-commit');
-    // 5. Print summary
-    console.log(`\n\u2705 Done! Created ${createdFiles.length} files.`);
-    if (skippedFiles.length > 0) {
-        console.log(`   Skipped ${skippedFiles.length} existing files.`);
-    }
+    sp.succeed(`Git hooks                  ${dim('1 file')}`);
+    // 5. Print final summary
+    console.log();
+    console.log(doubleBoxWithHeader([`             ${green(bold('\u2713 Setup complete!'))}                  `], [
+        `Created: ${bold(String(createdFiles.length))} files${' '.repeat(34 - String(createdFiles.length).length)}`,
+        `Skipped: ${bold(String(skippedFiles.length))} files${' '.repeat(34 - String(skippedFiles.length).length)}`
+    ]));
     console.log(`
-Next steps:
-  1. Set up Supabase and add .env with PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY and PUBLIC_SUPABASE_URL
-  2. Run supabase-schema.sql in the Supabase SQL Editor
-  3. Add your app icons: static/favicon.png, static/icon-192.png, static/icon-512.png
-  4. Start building: npm run dev`);
+  ${bold('Next steps:')}
+    1. Set up Supabase and add .env with your keys
+    2. Run supabase-schema.sql in Supabase SQL Editor
+    3. Add app icons in static/icons/
+    4. Start building: ${cyan('npm run dev')}
+`);
 }
 // =============================================================================
 //                                 RUN
 // =============================================================================
-main().catch((err) => {
-    console.error('Error:', err);
-    process.exit(1);
-});
+routeCommand();
 //# sourceMappingURL=install-pwa.js.map