Upload folder using huggingface_hub (part 2)

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+desktop/electron/icons/icon.icns filter=lfs diff=lfs merge=lfs -text

components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

components/ui/discord-icon.tsx

@@ -0,0 +1,18 @@
+'use client';
+
+interface DiscordIconProps {
+  className?: string;
+}
+
+export function DiscordIcon({ className }: DiscordIconProps) {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 64 48"
+      fill="currentColor"
+      className={className}
+    >
+      <path d="M40.575 0C39.9562 1.09866 39.4006 2.2352 38.8954 3.397C34.0967 2.67719 29.2096 2.67719 24.3982 3.397C23.9057 2.2352 23.3374 1.09866 22.7186 0C18.2104 0.770324 13.8157 2.12155 9.64839 4.02841C1.38951 16.2652 -0.845688 28.1863 0.265599 39.9432C5.10222 43.517 10.5197 46.2447 16.2909 47.9874C17.5916 46.2447 18.7407 44.3883 19.7257 42.4562C17.8568 41.7616 16.0509 40.8903 14.3208 39.88C14.7755 39.5517 15.2175 39.2107 15.6468 38.8824C25.7873 43.6559 37.5316 43.6559 47.6847 38.8824C48.1141 39.236 48.5561 39.577 49.0107 39.88C47.2806 40.9029 45.4748 41.7616 43.5931 42.4688C44.5781 44.4009 45.7273 46.2573 47.028 48C52.7991 46.2573 58.2167 43.5422 63.0533 39.9684C64.3666 26.3299 60.8055 14.5099 53.6452 4.04104C49.4905 2.13418 45.0959 0.782952 40.5876 0.0252565L40.575 0ZM21.1401 32.7072C18.0209 32.7072 15.4321 29.8785 15.4321 26.3804C15.4321 22.8824 17.9199 20.041 21.1275 20.041C24.3351 20.041 26.886 22.895 26.8354 26.3804C26.7849 29.8658 24.3224 32.7072 21.1401 32.7072ZM42.1788 32.7072C39.047 32.7072 36.4834 29.8785 36.4834 26.3804C36.4834 22.8824 38.9712 20.041 42.1788 20.041C45.3864 20.041 47.9246 22.895 47.8741 26.3804C47.8236 29.8658 45.3611 32.7072 42.1788 32.7072Z" />
+    </svg>
+  );
+}

components/ui/dropdown-menu.tsx

@@ -0,0 +1,257 @@
+"use client";
+
+import * as React from "react";
+import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
+import { CheckIcon, ChevronRightIcon, CircleIcon } from "lucide-react";
+
+import { cn } from "@/lib/utils";
+
+function DropdownMenu({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Root>) {
+  return <DropdownMenuPrimitive.Root data-slot="dropdown-menu" {...props} />;
+}
+
+function DropdownMenuPortal({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Portal>) {
+  return (
+    <DropdownMenuPrimitive.Portal data-slot="dropdown-menu-portal" {...props} />
+  );
+}
+
+function DropdownMenuTrigger({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Trigger>) {
+  return (
+    <DropdownMenuPrimitive.Trigger
+      data-slot="dropdown-menu-trigger"
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuContent({
+  className,
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Content>) {
+  return (
+    <DropdownMenuPrimitive.Portal>
+      <DropdownMenuPrimitive.Content
+        data-slot="dropdown-menu-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-[100] max-h-(--radix-dropdown-menu-content-available-height) min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border p-1 shadow-lg",
+          className
+        )}
+        {...props}
+      />
+    </DropdownMenuPrimitive.Portal>
+  );
+}
+
+function DropdownMenuGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Group>) {
+  return (
+    <DropdownMenuPrimitive.Group data-slot="dropdown-menu-group" {...props} />
+  );
+}
+
+function DropdownMenuItem({
+  className,
+  inset,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Item> & {
+  inset?: boolean;
+  variant?: "default" | "destructive";
+}) {
+  return (
+    <DropdownMenuPrimitive.Item
+      data-slot="dropdown-menu-item"
+      data-inset={inset}
+      data-variant={variant}
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground data-[variant=destructive]:text-destructive data-[variant=destructive]:focus:bg-destructive/10 dark:data-[variant=destructive]:focus:bg-destructive/20 data-[variant=destructive]:focus:text-destructive data-[variant=destructive]:*:[svg]:!text-destructive [&_svg:not([class*='text-'])]:text-muted-foreground relative flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuCheckboxItem({
+  className,
+  children,
+  checked,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.CheckboxItem>) {
+  return (
+    <DropdownMenuPrimitive.CheckboxItem
+      data-slot="dropdown-menu-checkbox-item"
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      checked={checked}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CheckIcon className="size-4" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.CheckboxItem>
+  );
+}
+
+function DropdownMenuRadioGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+  return (
+    <DropdownMenuPrimitive.RadioGroup
+      data-slot="dropdown-menu-radio-group"
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuRadioItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>) {
+  return (
+    <DropdownMenuPrimitive.RadioItem
+      data-slot="dropdown-menu-radio-item"
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <CircleIcon className="size-2 fill-current" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.RadioItem>
+  );
+}
+
+function DropdownMenuLabel({
+  className,
+  inset,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Label> & {
+  inset?: boolean;
+}) {
+  return (
+    <DropdownMenuPrimitive.Label
+      data-slot="dropdown-menu-label"
+      data-inset={inset}
+      className={cn(
+        "px-2 py-1.5 text-sm font-medium data-[inset]:pl-8",
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Separator>) {
+  return (
+    <DropdownMenuPrimitive.Separator
+      data-slot="dropdown-menu-separator"
+      className={cn("bg-border -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuShortcut({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      data-slot="dropdown-menu-shortcut"
+      className={cn(
+        "text-muted-foreground ml-auto text-xs tracking-widest",
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function DropdownMenuSub({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+  return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />;
+}
+
+function DropdownMenuSubTrigger({
+  className,
+  inset,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger> & {
+  inset?: boolean;
+}) {
+  return (
+    <DropdownMenuPrimitive.SubTrigger
+      data-slot="dropdown-menu-sub-trigger"
+      data-inset={inset}
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground flex cursor-default items-center rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[inset]:pl-8",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <ChevronRightIcon className="ml-auto size-4" />
+    </DropdownMenuPrimitive.SubTrigger>
+  );
+}
+
+function DropdownMenuSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+  return (
+    <DropdownMenuPrimitive.SubContent
+      data-slot="dropdown-menu-sub-content"
+      className={cn(
+        "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 min-w-[8rem] origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border p-1 shadow-lg",
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  DropdownMenu,
+  DropdownMenuPortal,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuLabel,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuSub,
+  DropdownMenuSubTrigger,
+  DropdownMenuSubContent,
+};

components/ui/input.tsx

@@ -0,0 +1,21 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input flex h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        "focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]",
+        "aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }

components/ui/label.tsx

@@ -0,0 +1,26 @@
+'use client'
+
+import * as React from 'react'
+import * as LabelPrimitive from '@radix-ui/react-label'
+import { cva, type VariantProps } from 'class-variance-authority'
+
+import { cn } from '@/lib/utils'
+
+const labelVariants = cva(
+  'text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70'
+)
+
+const Label = React.forwardRef<
+  React.ElementRef<typeof LabelPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root> &
+    VariantProps<typeof labelVariants>
+>(({ className, ...props }, ref) => (
+  <LabelPrimitive.Root
+    ref={ref}
+    className={cn(labelVariants(), className)}
+    {...props}
+  />
+))
+Label.displayName = LabelPrimitive.Root.displayName
+
+export { Label }

components/ui/logo.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+interface LogoProps {
+  width?: number;
+  height?: number;
+  className?: string;
+}
+
+// Letter fill uses `currentColor` (driven by Tailwind `text-*`/`dark:text-*`);
+// background uses `--logo-bg` var so theme inversion works without prop plumbing.
+export function Logo({ width = 64, height = 64, className }: LogoProps) {
+  return (
+    <svg
+      width={width}
+      height={height}
+      viewBox="0 0 256 256"
+      preserveAspectRatio="xMidYMid meet"
+      xmlns="http://www.w3.org/2000/svg"
+      className={`text-white dark:text-black [--logo-bg:#000000] dark:[--logo-bg:#ffffff] ${className ?? ''}`}
+    >
+      <rect x="0" y="0" width="256" height="256" rx="20" ry="20" fill="var(--logo-bg)" />
+      <g transform="translate(0,256) scale(0.0476,-0.0476)" fill="currentColor" stroke="none">
+        <path d="M725 4825 c-50 -18 -100 -71 -114 -122 -15 -54 -15 -1573 0 -1628 16 -55 44 -92 89 -115 38 -19 62 -20 855 -20 781 0 817 1 853 19 46 23 67 46 87 94 13 32 15 138 15 830 0 566 -3 804 -11 828 -16 45 -55 87 -104 110 -38 18 -82 19 -835 18 -659 0 -802 -2 -835 -14z m1351 -371 c15 -11 37 -33 48 -48 21 -27 21 -38 21 -520 0 -547 3 -523 -68 -566 -31 -19 -54 -20 -521 -20 -483 0 -489 0 -524 22 -20 12 -42 38 -53 62 -17 38 -19 74 -19 504 0 496 1 503 51 548 46 41 66 43 561 41 464 -2 477 -3 504 -23z" />
+        <path d="M3058 4830 c-44 -13 -87 -49 -108 -90 -19 -37 -20 -61 -20 -471 0 -428 0 -432 22 -471 13 -22 41 -51 64 -64 41 -24 41 -24 685 -24 645 0 645 0 689 -22 63 -33 80 -71 80 -183 0 -101 -15 -144 -63 -179 -28 -21 -41 -21 -695 -26 -666 -5 -667 -5 -702 -27 -109 -68 -106 -247 5 -310 40 -23 40 -23 858 -23 664 0 824 3 850 14 43 17 95 78 102 118 3 18 5 225 3 459 -3 426 -3 426 -31 462 -58 76 -15 71 -757 77 -620 5 -667 6 -692 23 -44 30 -58 74 -58 179 0 116 16 153 80 186 44 22 44 22 693 22 710 0 678 -3 731 60 80 96 41 240 -79 287 -35 14 -1612 17 -1657 3z" />
+        <path d="M702 2509 c-48 -24 -75 -57 -91 -114 -9 -29 -11 -253 -9 -840 3 -779 4 -801 23 -834 11 -19 37 -48 58 -65 39 -31 39 -31 380 -31 342 0 342 0 399 28 31 15 63 39 73 53 16 25 16 25 62 -16 77 -67 104 -71 470 -68 320 3 320 3 360 30 24 16 49 44 62 70 21 44 21 49 21 854 0 773 -1 811 -19 851 -35 76 -135 120 -215 93 -41 -13 -90 -51 -109 -84 -9 -16 -13 -187 -17 -688 -5 -654 -5 -667 -26 -694 -43 -58 -68 -69 -169 -72 -82 -3 -99 -1 -133 18 -22 12 -49 39 -61 60 -21 37 -21 45 -21 664 0 439 -3 641 -11 673 -32 123 -190 174 -285 91 -73 -64 -69 -20 -70 -743 0 -721 3 -687 -66 -737 -28 -20 -47 -23 -133 -26 -91 -3 -103 -2 -134 20 -19 13 -44 36 -55 51 -21 28 -21 38 -26 695 -4 481 -8 673 -17 687 -50 87 -152 118 -241 74z" />
+        <path d="M3047 2515 c-47 -16 -81 -46 -101 -90 -14 -28 -16 -95 -16 -463 0 -281 4 -440 11 -459 15 -40 48 -73 94 -94 38 -17 79 -19 685 -19 626 0 646 -1 678 -20 58 -35 72 -72 72 -185 0 -110 -14 -147 -67 -182 -25 -17 -73 -18 -698 -23 -672 -5 -672 -5 -708 -33 -20 -15 -44 -42 -53 -60 -21 -39 -21 -125 -1 -163 20 -38 65 -80 100 -93 19 -8 289 -11 833 -11 701 0 809 2 841 15 48 20 71 41 94 88 19 35 19 60 17 480 -3 444 -3 444 -30 479 -54 71 -23 68 -740 68 -612 0 -645 1 -685 20 -67 30 -83 66 -83 183 0 116 14 156 68 189 35 21 35 21 691 22 606 1 658 2 688 19 137 74 130 264 -12 328 -38 18 -85 19 -840 18 -652 0 -807 -2 -838 -14z" />
+      </g>
+    </svg>
+  );
+}

components/ui/pagination.tsx

@@ -0,0 +1,145 @@
+'use client';
+
+import React from 'react';
+import { ChevronLeft, ChevronRight } from 'lucide-react';
+import { cn } from '@/lib/utils';
+
+export interface PaginationProps {
+  page: number;
+  totalPages: number;
+  onPageChange: (page: number) => void;
+  /**
+   * Optional scroll container to reset to top on page change. Defaults to
+   * window scroll when omitted. Passing `null` disables scroll-to-top.
+   */
+  scrollTarget?: React.RefObject<HTMLElement | null> | null;
+  className?: string;
+}
+
+export interface PaginationRangeProps {
+  total: number;
+  rangeStart: number;
+  rangeEnd: number;
+  totalPages: number;
+  className?: string;
+}
+
+/**
+ * Build a compact page list with ellipsis:
+ *   1  ... 4 5 6 ...  12
+ * Always includes first, last, current ±1.
+ */
+function buildPageList(page: number, totalPages: number): Array<number | 'ellipsis'> {
+  if (totalPages <= 7) {
+    return Array.from({ length: totalPages }, (_, i) => i + 1);
+  }
+
+  const set = new Set<number>([1, totalPages, page - 1, page, page + 1]);
+  const pages = Array.from(set)
+    .filter(p => p >= 1 && p <= totalPages)
+    .sort((a, b) => a - b);
+
+  const out: Array<number | 'ellipsis'> = [];
+  for (let i = 0; i < pages.length; i++) {
+    out.push(pages[i]);
+    if (i < pages.length - 1 && pages[i + 1] - pages[i] > 1) {
+      out.push('ellipsis');
+    }
+  }
+  return out;
+}
+
+/**
+ * Small "N–M of T" range label. Renders nothing when the list fits on a
+ * single page — lets callers place it unconditionally without a guard.
+ */
+export function PaginationRange({
+  total,
+  rangeStart,
+  rangeEnd,
+  totalPages,
+  className,
+}: PaginationRangeProps) {
+  if (totalPages <= 1) return null;
+  return (
+    <p className={cn('text-[11px] text-muted-foreground', className)}>
+      {rangeStart}–{rangeEnd} of {total}
+    </p>
+  );
+}
+
+export function Pagination({
+  page,
+  totalPages,
+  onPageChange,
+  scrollTarget,
+  className,
+}: PaginationProps) {
+  if (totalPages <= 1) return null;
+
+  const pageList = buildPageList(page, totalPages);
+  const canPrev = page > 1;
+  const canNext = page < totalPages;
+
+  const handleChange = (p: number) => {
+    if (p === page) return;
+    onPageChange(p);
+    // Default: scroll window. Explicit null disables. Ref → scroll that element.
+    if (scrollTarget === null) return;
+    const el = scrollTarget?.current;
+    try {
+      if (el) {
+        el.scrollTo({ top: 0, behavior: 'smooth' });
+      } else if (typeof window !== 'undefined') {
+        window.scrollTo({ top: 0, behavior: 'smooth' });
+      }
+    } catch {
+      // Older browsers: ignore.
+    }
+  };
+
+  const navBtn = "h-6 w-6 inline-flex items-center justify-center rounded text-muted-foreground hover:text-foreground hover:bg-muted/60 disabled:opacity-40 disabled:pointer-events-none transition-colors";
+  const pageBtn = "h-6 min-w-6 px-1.5 inline-flex items-center justify-center rounded text-[11px] text-muted-foreground hover:text-foreground hover:bg-muted/60 transition-colors";
+  const pageBtnActive = "h-6 min-w-6 px-1.5 inline-flex items-center justify-center rounded text-[11px] font-medium text-foreground bg-muted";
+
+  return (
+    <div className={cn('flex items-center justify-center gap-0.5 pt-4 pb-1', className)}>
+      <button
+        type="button"
+        className={navBtn}
+        onClick={() => handleChange(page - 1)}
+        disabled={!canPrev}
+        aria-label="Previous page"
+      >
+        <ChevronLeft className="h-3.5 w-3.5" />
+      </button>
+
+      {pageList.map((p, i) =>
+        p === 'ellipsis' ? (
+          <span key={`e-${i}`} className="px-1 text-[11px] text-muted-foreground/60">…</span>
+        ) : (
+          <button
+            key={p}
+            type="button"
+            className={p === page ? pageBtnActive : pageBtn}
+            onClick={() => handleChange(p)}
+            aria-label={`Page ${p}`}
+            aria-current={p === page ? 'page' : undefined}
+          >
+            {p}
+          </button>
+        )
+      )}
+
+      <button
+        type="button"
+        className={navBtn}
+        onClick={() => handleChange(page + 1)}
+        disabled={!canNext}
+        aria-label="Next page"
+      >
+        <ChevronRight className="h-3.5 w-3.5" />
+      </button>
+    </div>
+  );
+}

components/ui/panel.tsx

@@ -0,0 +1,90 @@
+import React, { createContext, useContext } from 'react';
+import { X, GripVertical } from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+
+// Context for panel drag-to-reorder
+interface PanelDragContext {
+  onDragStart: (panelKey: string) => void;
+  draggingPanel: string | null;
+}
+const PanelDragCtx = createContext<PanelDragContext | null>(null);
+export const PanelDragProvider = PanelDragCtx.Provider;
+
+interface PanelContainerProps {
+  children: React.ReactNode;
+  className?: string;
+  dataTourId?: string;
+}
+
+export function PanelContainer({ children, className, dataTourId }: PanelContainerProps) {
+  return (
+    <div
+      className={`h-full flex flex-col bg-card border border-border md:rounded-lg overflow-hidden ${className || ''}`}
+      {...(dataTourId ? { 'data-tour-id': dataTourId } : {})}
+    >
+      {children}
+    </div>
+  );
+}
+
+interface PanelHeaderProps {
+  icon: LucideIcon;
+  title: string;
+  color?: string;
+  onClose?: () => void;
+  /** Inline content after the title (e.g. counts, badges) */
+  children?: React.ReactNode;
+  /** Action buttons on the right side of the header (before the close button) */
+  actions?: React.ReactNode;
+  /** Panel key for drag-to-reorder (enables drag handle when PanelDragProvider is present) */
+  panelKey?: string;
+}
+
+export function PanelHeader({ icon: Icon, title, color, onClose, children, actions, panelKey }: PanelHeaderProps) {
+  const dragCtx = useContext(PanelDragCtx);
+  const isDragging = dragCtx && panelKey ? dragCtx.draggingPanel === panelKey : false;
+  const canDrag = dragCtx && panelKey;
+
+  const hasActions = Boolean(actions) || Boolean(children);
+
+  return (
+    <div className={`flex items-center justify-end md:justify-between px-3 py-1.5 md:py-2 border-b border-border bg-muted/30 shrink-0 ${isDragging ? 'opacity-50' : ''} ${!hasActions ? 'md:flex hidden' : ''}`}>
+      <div className="hidden md:flex items-center gap-2">
+        <Icon className="h-4 w-4" style={color ? { color } : undefined} />
+        <span className="font-semibold text-sm">{title}</span>
+        {children}
+      </div>
+      {children && <div className="flex md:hidden items-center gap-2">{children}</div>}
+      <div className="flex items-center gap-1.5 md:gap-1">
+        {actions}
+        <div className="hidden md:flex items-center gap-0.5 ml-1 pl-1 border-l border-border/50">
+          {canDrag && (
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-5 w-5 cursor-grab active:cursor-grabbing"
+              title="Drag to reorder"
+              onMouseDown={() => {
+                dragCtx.onDragStart(panelKey);
+              }}
+            >
+              <GripVertical className="h-3 w-3" />
+            </Button>
+          )}
+          {onClose && (
+            <Button
+              variant="ghost"
+              size="icon"
+              onClick={onClose}
+              className="h-5 w-5"
+              title={`Close ${title.toLowerCase()} panel`}
+            >
+              <X className="h-3 w-3" />
+            </Button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

components/ui/popover.tsx

@@ -0,0 +1,50 @@
+"use client";
+
+import * as React from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+
+import { cn } from "@/lib/utils";
+
+function Popover({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Root>) {
+  return <PopoverPrimitive.Root data-slot="popover" {...props} />;
+}
+
+function PopoverTrigger({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
+  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />;
+}
+
+function PopoverContent({
+  className,
+  align = "center",
+  sideOffset = 4,
+  collisionPadding = 16,
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Content>) {
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Content
+        data-slot="popover-content"
+        align={align}
+        sideOffset={sideOffset}
+        collisionPadding={collisionPadding}
+        className={cn(
+          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden",
+          className
+        )}
+        {...props}
+      />
+    </PopoverPrimitive.Portal>
+  );
+}
+
+function PopoverAnchor({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Anchor>) {
+  return <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />;
+}
+
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor };

components/ui/resizable.tsx

@@ -0,0 +1,45 @@
+'use client'
+
+import { GripVertical } from 'lucide-react'
+import * as ResizablePrimitive from 'react-resizable-panels'
+
+import { cn } from '@/lib/utils'
+
+const ResizablePanelGroup = ({
+  className,
+  ...props
+}: React.ComponentProps<typeof ResizablePrimitive.PanelGroup>) => (
+  <ResizablePrimitive.PanelGroup
+    className={cn(
+      'flex h-full w-full data-[panel-group-direction=vertical]:flex-col',
+      className
+    )}
+    {...props}
+  />
+)
+
+const ResizablePanel = ResizablePrimitive.Panel
+
+const ResizableHandle = ({
+  withHandle,
+  className,
+  ...props
+}: React.ComponentProps<typeof ResizablePrimitive.PanelResizeHandle> & {
+  withHandle?: boolean
+}) => (
+  <ResizablePrimitive.PanelResizeHandle
+    className={cn(
+      'group relative flex w-2 mx-1 items-center justify-center bg-transparent hover:bg-border/50 transition-colors after:absolute after:inset-y-0 after:left-1/2 after:w-4 after:-translate-x-1/2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1 data-[panel-group-direction=vertical]:h-2 data-[panel-group-direction=vertical]:my-1 data-[panel-group-direction=vertical]:mx-0 data-[panel-group-direction=vertical]:w-full data-[panel-group-direction=vertical]:after:left-0 data-[panel-group-direction=vertical]:after:h-4 data-[panel-group-direction=vertical]:after:w-full data-[panel-group-direction=vertical]:after:-translate-y-1/2 data-[panel-group-direction=vertical]:after:translate-x-0 [&[data-panel-group-direction=vertical]>div]:rotate-90 cursor-col-resize data-[panel-group-direction=vertical]:cursor-row-resize',
+      className
+    )}
+    {...props}
+  >
+    {withHandle && (
+      <div className="z-10 flex h-12 w-1 items-center justify-center rounded-full bg-border/30 hover:bg-border/50 transition-colors opacity-0 group-hover:opacity-100">
+        <GripVertical className="h-3 w-3 text-muted-foreground/50" />
+      </div>
+    )}
+  </ResizablePrimitive.PanelResizeHandle>
+)
+
+export { ResizablePanelGroup, ResizablePanel, ResizableHandle }

components/ui/select.tsx

@@ -0,0 +1,185 @@
+"use client"
+
+import * as React from "react"
+import * as SelectPrimitive from "@radix-ui/react-select"
+import { CheckIcon, ChevronDownIcon, ChevronUpIcon } from "lucide-react"
+
+import { cn } from "@/lib/utils"
+
+function Select({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Root>) {
+  return <SelectPrimitive.Root data-slot="select" {...props} />
+}
+
+function SelectGroup({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Group>) {
+  return <SelectPrimitive.Group data-slot="select-group" {...props} />
+}
+
+function SelectValue({
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Value>) {
+  return <SelectPrimitive.Value data-slot="select-value" {...props} />
+}
+
+function SelectTrigger({
+  className,
+  size = "default",
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Trigger> & {
+  size?: "sm" | "default"
+}) {
+  return (
+    <SelectPrimitive.Trigger
+      data-slot="select-trigger"
+      data-size={size}
+      className={cn(
+        "border-input data-[placeholder]:text-muted-foreground [&_svg:not([class*='text-'])]:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 dark:hover:bg-input/50 flex w-fit items-center justify-between gap-2 rounded-md border bg-transparent px-3 py-2 text-sm whitespace-nowrap shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 data-[size=default]:h-9 data-[size=sm]:h-8 *:data-[slot=select-value]:line-clamp-1 *:data-[slot=select-value]:flex *:data-[slot=select-value]:items-center *:data-[slot=select-value]:gap-2 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    >
+      {children}
+      <SelectPrimitive.Icon asChild>
+        <ChevronDownIcon className="size-4 opacity-50" />
+      </SelectPrimitive.Icon>
+    </SelectPrimitive.Trigger>
+  )
+}
+
+function SelectContent({
+  className,
+  children,
+  position = "popper",
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Content>) {
+  return (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Content
+        data-slot="select-content"
+        className={cn(
+          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 relative z-50 max-h-(--radix-select-content-available-height) min-w-[8rem] origin-(--radix-select-content-transform-origin) overflow-x-hidden overflow-y-auto rounded-md border shadow-md",
+          position === "popper" &&
+            "data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1",
+          className
+        )}
+        position={position}
+        {...props}
+      >
+        <SelectScrollUpButton />
+        <SelectPrimitive.Viewport
+          className={cn(
+            "p-1",
+            position === "popper" &&
+              "h-[var(--radix-select-trigger-height)] w-full min-w-[var(--radix-select-trigger-width)] scroll-my-1"
+          )}
+        >
+          {children}
+        </SelectPrimitive.Viewport>
+        <SelectScrollDownButton />
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Portal>
+  )
+}
+
+function SelectLabel({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Label>) {
+  return (
+    <SelectPrimitive.Label
+      data-slot="select-label"
+      className={cn("text-muted-foreground px-2 py-1.5 text-xs", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Item>) {
+  return (
+    <SelectPrimitive.Item
+      data-slot="select-item"
+      className={cn(
+        "focus:bg-accent focus:text-accent-foreground [&_svg:not([class*='text-'])]:text-muted-foreground relative flex w-full cursor-default items-center gap-2 rounded-sm py-1.5 pr-8 pl-2 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 *:[span]:last:flex *:[span]:last:items-center *:[span]:last:gap-2",
+        className
+      )}
+      {...props}
+    >
+      <span className="absolute right-2 flex size-3.5 items-center justify-center">
+        <SelectPrimitive.ItemIndicator>
+          <CheckIcon className="size-4" />
+        </SelectPrimitive.ItemIndicator>
+      </span>
+      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+    </SelectPrimitive.Item>
+  )
+}
+
+function SelectSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.Separator>) {
+  return (
+    <SelectPrimitive.Separator
+      data-slot="select-separator"
+      className={cn("bg-border pointer-events-none -mx-1 my-1 h-px", className)}
+      {...props}
+    />
+  )
+}
+
+function SelectScrollUpButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollUpButton>) {
+  return (
+    <SelectPrimitive.ScrollUpButton
+      data-slot="select-scroll-up-button"
+      className={cn(
+        "flex cursor-default items-center justify-center py-1",
+        className
+      )}
+      {...props}
+    >
+      <ChevronUpIcon className="size-4" />
+    </SelectPrimitive.ScrollUpButton>
+  )
+}
+
+function SelectScrollDownButton({
+  className,
+  ...props
+}: React.ComponentProps<typeof SelectPrimitive.ScrollDownButton>) {
+  return (
+    <SelectPrimitive.ScrollDownButton
+      data-slot="select-scroll-down-button"
+      className={cn(
+        "flex cursor-default items-center justify-center py-1",
+        className
+      )}
+      {...props}
+    >
+      <ChevronDownIcon className="size-4" />
+    </SelectPrimitive.ScrollDownButton>
+  )
+}
+
+export {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectLabel,
+  SelectScrollDownButton,
+  SelectScrollUpButton,
+  SelectSeparator,
+  SelectTrigger,
+  SelectValue,
+}

components/ui/sonner.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import { useTheme } from "next-themes";
+import { Toaster as Sonner, ToasterProps } from "sonner";
+
+const Toaster = ({ ...props }: ToasterProps) => {
+  const { theme } = useTheme();
+  
+  return (
+    <Sonner
+      theme={theme as ToasterProps["theme"]}
+      className="toaster group"
+      closeButton
+      style={
+        {
+          "--normal-bg": "var(--popover)",
+          "--normal-text": "var(--popover-foreground)",
+          "--normal-border": "var(--border)",
+        } as React.CSSProperties
+      }
+      {...props}
+    />
+  );
+};
+
+export { Toaster };

components/ui/spinner.tsx

@@ -0,0 +1,34 @@
+import { cn } from '@/lib/utils';
+
+interface SpinnerProps {
+  className?: string;
+  size?: number;
+  color?: string;
+}
+
+export function Spinner({ className, size = 48, color }: SpinnerProps) {
+  const r = 18; // radius
+  const circumference = 2 * Math.PI * r;
+  const arcLength = circumference * 0.7; // 70% arc
+
+  return (
+    <svg
+      className={cn('animate-spin', className)}
+      width={size}
+      height={size}
+      viewBox="0 0 44 44"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <circle
+        cx="22"
+        cy="22"
+        r={r}
+        stroke={color || 'currentColor'}
+        strokeWidth="3"
+        strokeLinecap="round"
+        strokeDasharray={`${arcLength} ${circumference - arcLength}`}
+      />
+    </svg>
+  );
+}

components/ui/switch.tsx

@@ -0,0 +1,31 @@
+"use client"
+
+import * as React from "react"
+import * as SwitchPrimitive from "@radix-ui/react-switch"
+
+import { cn } from "@/lib/utils"
+
+function Switch({
+  className,
+  ...props
+}: React.ComponentProps<typeof SwitchPrimitive.Root>) {
+  return (
+    <SwitchPrimitive.Root
+      data-slot="switch"
+      className={cn(
+        "peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 dark:data-[state=unchecked]:bg-input/80 inline-flex h-[1.15rem] w-8 shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
+        className
+      )}
+      {...props}
+    >
+      <SwitchPrimitive.Thumb
+        data-slot="switch-thumb"
+        className={cn(
+          "bg-background dark:data-[state=unchecked]:bg-foreground dark:data-[state=checked]:bg-primary-foreground pointer-events-none block size-4 rounded-full ring-0 transition-transform data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-0"
+        )}
+      />
+    </SwitchPrimitive.Root>
+  )
+}
+
+export { Switch }

components/ui/tabs.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import * as React from 'react';
+import * as TabsPrimitive from '@radix-ui/react-tabs';
+
+import { cn } from '@/lib/utils';
+
+const Tabs = TabsPrimitive.Root;
+
+const TabsList = React.forwardRef<
+  React.ElementRef<typeof TabsPrimitive.List>,
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.List>
+>(({ className, ...props }, ref) => (
+  <TabsPrimitive.List
+    ref={ref}
+    className={cn(
+      'inline-flex h-10 items-center justify-center rounded-md bg-muted p-1 text-muted-foreground',
+      className
+    )}
+    {...props}
+  />
+));
+TabsList.displayName = TabsPrimitive.List.displayName;
+
+const TabsTrigger = React.forwardRef<
+  React.ElementRef<typeof TabsPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Trigger>
+>(({ className, ...props }, ref) => (
+  <TabsPrimitive.Trigger
+    ref={ref}
+    className={cn(
+      'inline-flex items-center justify-center whitespace-nowrap rounded-sm px-3 py-1.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
+      className
+    )}
+    {...props}
+  />
+));
+TabsTrigger.displayName = TabsPrimitive.Trigger.displayName;
+
+const TabsContent = React.forwardRef<
+  React.ElementRef<typeof TabsPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof TabsPrimitive.Content>
+>(({ className, ...props }, ref) => (
+  <TabsPrimitive.Content
+    ref={ref}
+    className={cn(
+      'mt-2 ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+      className
+    )}
+    {...props}
+  />
+));
+TabsContent.displayName = TabsPrimitive.Content.displayName;
+
+export { Tabs, TabsList, TabsTrigger, TabsContent };

components/ui/textarea.tsx

@@ -0,0 +1,22 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+const Textarea = React.forwardRef<
+  HTMLTextAreaElement,
+  React.ComponentProps<"textarea">
+>(({ className, ...props }, ref) => {
+  return (
+    <textarea
+      className={cn(
+        "flex min-h-[84px] w-full rounded-md border border-input bg-background px-3 py-2 text-base ring-offset-background placeholder:text-muted-foreground disabled:cursor-not-allowed disabled:opacity-50 md:text-sm",
+        className
+      )}
+      ref={ref}
+      {...props}
+    />
+  )
+})
+Textarea.displayName = "Textarea"
+
+export { Textarea }

components/ui/thumbnail-area.tsx

@@ -0,0 +1,156 @@
+'use client';
+
+import React, { useRef, useState } from 'react';
+import { Camera, ImageUp, X, Loader2 } from 'lucide-react';
+import { compressImage } from '@/lib/utils/image-compress';
+import { cn } from '@/lib/utils';
+
+interface ThumbnailAreaProps {
+  image: string | undefined;
+  onCapture?: () => Promise<string | null>;  // undefined = capture unavailable
+  onImageChange: (image: string | undefined) => void;
+  size?: 'sm' | 'md';
+  className?: string;
+}
+
+export function ThumbnailArea({
+  image,
+  onCapture,
+  onImageChange,
+  size = 'md',
+  className,
+}: ThumbnailAreaProps) {
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [isCapturing, setIsCapturing] = useState(false);
+
+  const handleUpload = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const file = e.target.files?.[0];
+    if (!file) return;
+    try {
+      const compressed = await compressImage(file);
+      onImageChange(compressed);
+    } catch {
+      // silently fail — user can retry
+    }
+    // Reset input so re-selecting the same file triggers onChange
+    e.target.value = '';
+  };
+
+  const handleCapture = async (e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (!onCapture) return;
+    setIsCapturing(true);
+    try {
+      const result = await onCapture();
+      if (result) onImageChange(result);
+    } finally {
+      setIsCapturing(false);
+    }
+  };
+
+  const handleRemove = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    onImageChange(undefined);
+  };
+
+  const handleUploadClick = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    fileInputRef.current?.click();
+  };
+
+  const isSm = size === 'sm';
+
+  const btnBase = isSm
+    ? 'h-5 w-5 rounded'
+    : 'h-7 w-7 rounded-md';
+
+  const iconSize = isSm ? 'h-3 w-3' : 'h-3.5 w-3.5';
+
+  const stopProp = (e: React.MouseEvent) => e.stopPropagation();
+
+  if (image) {
+    return (
+      <div className={cn('relative group', className)} onClick={stopProp}>
+        {isSm ? (
+          <div className="w-16 h-12 rounded-md overflow-hidden bg-muted shrink-0">
+            <img src={image} alt="Thumbnail" className="w-full h-full object-cover" />
+          </div>
+        ) : (
+          <div className="w-full aspect-video bg-muted">
+            <img src={image} alt="Thumbnail" className="w-full h-full object-cover" />
+          </div>
+        )}
+        <button
+          type="button"
+          onClick={handleRemove}
+          className={cn(
+            'absolute flex items-center justify-center bg-background/80 text-foreground opacity-0 group-hover:opacity-100 transition-opacity border border-border shadow-sm',
+            btnBase,
+            isSm ? 'top-0 right-0 -translate-y-1/3 translate-x-1/3' : 'top-1.5 right-1.5'
+          )}
+          title="Remove thumbnail"
+        >
+          <X className={iconSize} />
+        </button>
+      </div>
+    );
+  }
+
+  // No image state
+  return (
+    <div className={cn('relative', className)} onClick={stopProp}>
+      {isSm ? (
+        <div className="w-16 h-12 rounded-md bg-muted flex items-center justify-center gap-1 shrink-0">
+          {onCapture && (
+            <button
+              type="button"
+              onClick={handleCapture}
+              disabled={isCapturing}
+              className="h-6 w-6 rounded flex items-center justify-center text-muted-foreground hover:text-foreground hover:bg-muted-foreground/15 transition-colors"
+              title="Capture"
+            >
+              {isCapturing ? <Loader2 className="h-3 w-3 animate-spin" /> : <Camera className="h-3 w-3" />}
+            </button>
+          )}
+          <button
+            type="button"
+            onClick={handleUploadClick}
+            className="h-6 w-6 rounded flex items-center justify-center text-muted-foreground hover:text-foreground hover:bg-muted-foreground/15 transition-colors"
+            title="Upload image"
+          >
+            <ImageUp className="h-3 w-3" />
+          </button>
+        </div>
+      ) : (
+        <div className="w-full aspect-video bg-muted flex items-center justify-center gap-3">
+          {onCapture && (
+            <button
+              type="button"
+              onClick={handleCapture}
+              disabled={isCapturing}
+              className="h-9 w-9 rounded-lg flex items-center justify-center border border-border/60 bg-background/50 text-muted-foreground hover:text-foreground hover:bg-background/80 transition-colors shadow-sm"
+              title="Capture screenshot"
+            >
+              {isCapturing ? <Loader2 className="h-4 w-4 animate-spin" /> : <Camera className="h-4 w-4" />}
+            </button>
+          )}
+          <button
+            type="button"
+            onClick={handleUploadClick}
+            className="h-9 w-9 rounded-lg flex items-center justify-center border border-border/60 bg-background/50 text-muted-foreground hover:text-foreground hover:bg-background/80 transition-colors shadow-sm"
+            title="Upload image"
+          >
+            <ImageUp className="h-4 w-4" />
+          </button>
+        </div>
+      )}
+      <input
+        ref={fileInputRef}
+        type="file"
+        accept="image/*"
+        className="hidden"
+        onChange={handleUpload}
+      />
+    </div>
+  );
+}

components/ui/toggle-group.tsx

@@ -0,0 +1,58 @@
+"use client"
+
+import * as React from "react"
+import * as ToggleGroupPrimitive from "@radix-ui/react-toggle-group"
+import { cva, type VariantProps } from "class-variance-authority"
+
+import { cn } from "@/lib/utils"
+
+const toggleGroupVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors hover:bg-muted hover:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 data-[state=on]:bg-accent data-[state=on]:text-accent-foreground",
+  {
+    variants: {
+      variant: {
+        default: "bg-transparent",
+        outline:
+          "border border-input bg-transparent shadow-sm hover:bg-accent hover:text-accent-foreground",
+      },
+      size: {
+        default: "h-9 px-3",
+        sm: "h-8 px-2",
+        lg: "h-10 px-3",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+
+const ToggleGroup = React.forwardRef<
+  React.ElementRef<typeof ToggleGroupPrimitive.Root>,
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Root>
+>(({ className, ...props }, ref) => (
+  <ToggleGroupPrimitive.Root
+    ref={ref}
+    className={cn("inline-flex items-center justify-center gap-1 rounded-md bg-muted p-1", className)}
+    {...props}
+  />
+))
+
+ToggleGroup.displayName = ToggleGroupPrimitive.Root.displayName
+
+const ToggleGroupItem = React.forwardRef<
+  React.ElementRef<typeof ToggleGroupPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof ToggleGroupPrimitive.Item> &
+    VariantProps<typeof toggleGroupVariants>
+>(({ className, variant, size, ...props }, ref) => (
+  <ToggleGroupPrimitive.Item
+    ref={ref}
+    className={cn(toggleGroupVariants({ variant, size }), className)}
+    {...props}
+  />
+))
+
+ToggleGroupItem.displayName = ToggleGroupPrimitive.Item.displayName
+
+export { ToggleGroup, ToggleGroupItem, toggleGroupVariants }

components/ui/tooltip.tsx

@@ -0,0 +1,65 @@
+"use client"
+
+import * as React from "react"
+import * as TooltipPrimitive from "@radix-ui/react-tooltip"
+
+import { cn } from "@/lib/utils"
+
+function TooltipProvider({
+  delayDuration = 0,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Provider>) {
+  return (
+    <TooltipPrimitive.Provider
+      data-slot="tooltip-provider"
+      delayDuration={delayDuration}
+      {...props}
+    />
+  )
+}
+
+function Tooltip({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Root>) {
+  return (
+    <TooltipProvider>
+      <TooltipPrimitive.Root data-slot="tooltip" {...props} />
+    </TooltipProvider>
+  )
+}
+
+function TooltipTrigger({
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return <TooltipPrimitive.Trigger data-slot="tooltip-trigger" {...props} />
+}
+
+function TooltipContent({
+  className,
+  sideOffset = 0,
+  children,
+  arrowStyle,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Content> & { arrowStyle?: React.CSSProperties }) {
+  return (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        data-slot="tooltip-content"
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-primary text-primary-foreground animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-fit origin-(--radix-tooltip-content-transform-origin) rounded-md px-3 py-1.5 text-xs text-balance",
+          className
+        )}
+        {...props}
+      >
+        {children}
+        <TooltipPrimitive.Arrow 
+          className="bg-primary fill-primary z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" 
+          style={arrowStyle}
+        />
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  )
+}
+
+export { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider }

components/views/content-area.tsx

@@ -0,0 +1,83 @@
+'use client';
+
+import React from 'react';
+import { Project } from '@/lib/vfs/types';
+import { logger } from '@/lib/utils';
+import { ProjectsView } from './projects-view';
+import { TemplatesView } from './templates-view';
+import { SkillsView } from './skills-view';
+import { InterviewsView } from './interviews-view';
+import { DeploymentsView } from './deployments-view';
+import { UsersView } from './users-view';
+import { WorkspacesView } from './workspaces-view';
+import { SettingsView } from './settings-view';
+import { DocsView } from './docs-view';
+import { DashboardView } from './dashboard-view';
+
+interface ContentAreaProps {
+  view: string;
+  workspaceId?: string;
+  onProjectSelect: (project: Project) => void;
+  settingsTab?: 'model' | 'application';
+  onNavigate?: (view: string) => void;
+  onStartTour?: () => void;
+  autoCreateProject?: boolean;
+}
+
+export function ContentArea({
+  view,
+  workspaceId,
+  onProjectSelect,
+  settingsTab,
+  onNavigate,
+  onStartTour,
+  autoCreateProject,
+}: ContentAreaProps) {
+  // Handler to select a project by ID (for dashboard recent projects click)
+  const handleProjectSelectById = async (projectId: string) => {
+    try {
+      const { vfs } = await import('@/lib/vfs');
+      await vfs.init();
+      const project = await vfs.getProject(projectId);
+      if (project) {
+        onProjectSelect(project);
+      } else {
+        logger.warn('[ContentArea] Project not found:', projectId);
+      }
+    } catch (err) {
+      logger.error('[ContentArea] Failed to load project:', err);
+    }
+  };
+
+  switch (view) {
+    case 'dashboard':
+      return (
+        <DashboardView
+          workspaceId={workspaceId}
+          onNavigate={onNavigate}
+          onProjectSelect={handleProjectSelectById}
+          onStartTour={onStartTour}
+        />
+      );
+    case 'projects':
+      return <ProjectsView onProjectSelect={onProjectSelect} autoCreate={autoCreateProject} workspaceId={workspaceId} />;
+    case 'deployments':
+      return <DeploymentsView onProjectSelect={onProjectSelect} workspaceId={workspaceId} />;
+    case 'users':
+      return <UsersView />;
+    case 'workspaces':
+      return <WorkspacesView />;
+    case 'templates':
+      return <TemplatesView onProjectSelect={(project) => handleProjectSelectById(project.id)} onNavigate={onNavigate} />;
+    case 'skills':
+      return <SkillsView />;
+    case 'interviews':
+      return <InterviewsView />;
+    case 'docs':
+      return <DocsView />;
+    case 'settings':
+      return <SettingsView tab={settingsTab} />;
+    default:
+      return <ProjectsView onProjectSelect={onProjectSelect} />;
+  }
+}

components/views/dashboard-view.tsx

@@ -0,0 +1,849 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import { useRouter } from 'next/navigation';
+import {
+  RefreshCw,
+  Plus,
+  FolderOpen,
+  Globe,
+  Sparkles,
+  BookOpen,
+  AlertTriangle,
+  ExternalLink,
+  Newspaper,
+  Clock,
+  ChevronRight,
+} from 'lucide-react';
+import { DiscordIcon } from '@/components/ui/discord-icon';
+import { Button } from '@/components/ui/button';
+import { Spinner } from '@/components/ui/spinner';
+import Link from 'next/link';
+import { vfs } from '@/lib/vfs';
+import { templateService } from '@/lib/vfs/template-service';
+import { skillsService } from '@/lib/vfs/skills';
+import pkg from '@/package.json';
+
+const isServerMode = process.env.NEXT_PUBLIC_SERVER_MODE === 'true';
+
+interface DashboardData {
+  system: {
+    version: string;
+    nodeVersion: string;
+    uptime: number;
+    memoryUsed: number;
+    memoryTotal: number;
+  };
+  content: {
+    projects: number;
+    templates: number;
+    skills: number;
+    totalFiles: number;
+  };
+  hosting: {
+    publishedDeployments: number;
+    deploymentsWithDb: number;
+    storageUsed: number;
+  };
+  traffic: {
+    requestsLastHour: number;
+    requestsLastDay: number;
+    errorCount: number;
+    topDeployments: Array<{ deploymentId: string; deploymentName: string; count: number }>;
+    recentErrors: Array<{ deploymentId: string; path: string; statusCode: number; timestamp: string }>;
+  };
+  whatsNew: {
+    version: string;
+    title: string;
+    highlights: string[];
+  };
+  recentProjects: Array<{
+    id: string;
+    name: string;
+    description: string | null;
+    updatedAt: string;
+  }>;
+  recentDeployments: Array<{
+    id: string;
+    name: string;
+    slug: string;
+    enabled: boolean;
+    publishedAt: string | null;
+    updatedAt: string;
+  }>;
+}
+
+// Browser mode data (subset of server mode)
+interface BrowserDashboardData {
+  content: {
+    projects: number;
+    templates: number;
+    skills: number;
+  };
+  whatsNew: {
+    version: string;
+    title: string;
+    highlights: string[];
+  } | null;
+  recentProjects: Array<{
+    id: string;
+    name: string;
+    description: string | null;
+    updatedAt: string;
+  }>;
+}
+
+// Fetch and parse the latest What's New entry from WHATS_NEW.md
+async function fetchWhatsNew(): Promise<BrowserDashboardData['whatsNew']> {
+  try {
+    const response = await fetch('/api/docs/WHATS_NEW.md');
+    if (!response.ok) return null;
+
+    const content = await response.text();
+    const versionMatch = content.match(/^## v(\d+\.\d+\.\d+)\s*-\s*(.+)$/m);
+    if (!versionMatch) return null;
+
+    const version = versionMatch[1];
+    const title = versionMatch[2].trim();
+    const versionIndex = content.indexOf(versionMatch[0]);
+    const afterVersion = content.substring(versionIndex + versionMatch[0].length);
+    const nextSectionMatch = afterVersion.match(/^(?:## |---)/m);
+    const sectionContent = nextSectionMatch
+      ? afterVersion.substring(0, nextSectionMatch.index)
+      : afterVersion;
+
+    const bulletRegex = /^[-*]\s+\*\*(.+?)\*\*\s*[-–]?\s*(.*)$/gm;
+    const highlights: string[] = [];
+    let match;
+
+    while ((match = bulletRegex.exec(sectionContent)) !== null && highlights.length < 4) {
+      const boldTitle = match[1].trim();
+      const description = match[2]?.trim();
+      highlights.push(description ? `${boldTitle} - ${description}` : boldTitle);
+    }
+
+    if (highlights.length === 0) {
+      const simpleBulletRegex = /^[-*]\s+(.+)$/gm;
+      while ((match = simpleBulletRegex.exec(sectionContent)) !== null && highlights.length < 4) {
+        const text = match[1].trim();
+        if (!text.match(/^\[.*\]\(.*\)$/)) {
+          highlights.push(text.replace(/\*\*/g, ''));
+        }
+      }
+    }
+
+    return { version, title, highlights };
+  } catch {
+    return null;
+  }
+}
+
+// Fetch dashboard data for browser mode (IndexedDB)
+async function fetchBrowserModeData(): Promise<BrowserDashboardData> {
+  await vfs.init();
+
+  const projects = await vfs.listProjects();
+  const templates = await templateService.listCustomTemplates();
+  const skills = await skillsService.getAllSkills();
+  const whatsNew = await fetchWhatsNew();
+
+  return {
+    content: {
+      projects: projects.length,
+      templates: templates.length,
+      skills: skills.length,
+    },
+    whatsNew,
+    recentProjects: projects
+      .sort((a, b) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
+      .slice(0, 3)
+      .map((p) => ({
+        id: p.id,
+        name: p.name,
+        description: p.description || null,
+        updatedAt: p.updatedAt instanceof Date ? p.updatedAt.toISOString() : p.updatedAt,
+      })),
+  };
+}
+
+function formatUptime(seconds: number): string {
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor((seconds % 86400) / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+
+  if (days > 0) {
+    return `${days}d ${hours}h`;
+  }
+  if (hours > 0) {
+    return `${hours}h ${minutes}m`;
+  }
+  return `${minutes}m`;
+}
+
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return parseFloat((bytes / Math.pow(k, i)).toFixed(1)) + ' ' + sizes[i];
+}
+
+function formatNumber(num: number): string {
+  if (num >= 1000000) {
+    return (num / 1000000).toFixed(1) + 'M';
+  }
+  if (num >= 1000) {
+    return (num / 1000).toFixed(1) + 'K';
+  }
+  return num.toString();
+}
+
+function formatRelativeTime(dateString: string): string {
+  const date = new Date(dateString);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffMins = Math.floor(diffMs / 60000);
+  const diffHours = Math.floor(diffMs / 3600000);
+  const diffDays = Math.floor(diffMs / 86400000);
+
+  if (diffMins < 1) return 'just now';
+  if (diffMins < 60) return `${diffMins}m ago`;
+  if (diffHours < 24) return `${diffHours}h ago`;
+  if (diffDays < 7) return `${diffDays}d ago`;
+  return date.toLocaleDateString();
+}
+
+// Quick Actions Bar
+function QuickActionsBar({
+  onStartTour,
+  onNavigate,
+}: {
+  onStartTour: () => void;
+  onNavigate?: (view: string) => void;
+}) {
+  // In browser mode, use onNavigate callback; in server mode, use Link
+  const projectsHref = isServerMode ? '/admin/projects?action=create' : '#';
+  const projectsListHref = isServerMode ? '/admin/projects' : '#';
+  const docsHref = isServerMode ? '/admin/docs' : '#';
+
+  const handleNewProjectClick = (e: React.MouseEvent) => {
+    if (!isServerMode && onNavigate) {
+      e.preventDefault();
+      onNavigate('projects:create');
+    }
+  };
+
+  const handleProjectsClick = (e: React.MouseEvent) => {
+    if (!isServerMode && onNavigate) {
+      e.preventDefault();
+      onNavigate('projects');
+    }
+  };
+
+  const handleDocsClick = (e: React.MouseEvent) => {
+    if (!isServerMode && onNavigate) {
+      e.preventDefault();
+      onNavigate('docs');
+    }
+  };
+
+  return (
+    <div className="bg-card rounded-xl border border-zinc-800 p-4 mb-6">
+      <div className="flex flex-wrap gap-2">
+        <Button variant="default" size="sm" asChild className="gap-1.5">
+          <Link href={projectsHref} onClick={handleNewProjectClick}>
+            <Plus className="w-4 h-4" />
+            New Project
+          </Link>
+        </Button>
+        <Button variant="outline" size="sm" asChild className="gap-1.5">
+          <Link href={projectsListHref} onClick={handleProjectsClick}>
+            <FolderOpen className="w-4 h-4" />
+            Projects
+          </Link>
+        </Button>
+        {isServerMode && (
+          <Button variant="outline" size="sm" asChild className="gap-1.5">
+            <Link href="/admin/deployments">
+              <Globe className="w-4 h-4" />
+              Deployments
+            </Link>
+          </Button>
+        )}
+        <Button variant="outline" size="sm" onClick={onStartTour} className="gap-1.5">
+          <Sparkles className="w-4 h-4" />
+          Guided Tour
+        </Button>
+        <Button variant="outline" size="sm" asChild className="gap-1.5">
+          <a href="https://discord.gg/mAJ8Ss4u" target="_blank" rel="noopener noreferrer">
+            <DiscordIcon className="w-4 h-4" />
+            Discord
+          </a>
+        </Button>
+        <Button variant="outline" size="sm" asChild className="gap-1.5">
+          <Link href={docsHref} onClick={handleDocsClick}>
+            <BookOpen className="w-4 h-4" />
+            Docs
+          </Link>
+        </Button>
+      </div>
+    </div>
+  );
+}
+
+// What's New Card - always visible, links to full changelog
+type WhatsNewProps = {
+  version: string;
+  title: string;
+  highlights?: string[];
+};
+
+function WhatsNewCard({
+  whatsNew,
+  onNavigate,
+}: {
+  whatsNew: WhatsNewProps;
+  onNavigate?: (view: string) => void;
+}) {
+  if (!whatsNew) return null;
+
+  const handleReadAll = (e: React.MouseEvent) => {
+    if (!isServerMode && onNavigate) {
+      e.preventDefault();
+      window.history.pushState({}, '', '/?doc=whats-new');
+      onNavigate('docs');
+    }
+  };
+
+  const docsHref = isServerMode ? '/admin/docs?doc=whats-new' : '#';
+
+  return (
+    <div className="bg-zinc-900/30 rounded-xl border border-zinc-800 p-4 flex flex-col">
+      <div className="flex items-start justify-between gap-4 mb-3">
+        <div className="flex items-center gap-2">
+          <Newspaper className="w-4 h-4 text-orange-500" />
+          <h3 className="text-sm font-medium text-zinc-200">
+            What&apos;s New in v{whatsNew.version}
+          </h3>
+        </div>
+        <Link
+          href={docsHref}
+          onClick={handleReadAll}
+          className="text-xs text-orange-500 hover:text-orange-400 flex items-center gap-1"
+        >
+          Read all
+          <ExternalLink className="w-3 h-3" />
+        </Link>
+      </div>
+      <p className="text-sm font-medium text-zinc-200 mb-2">{whatsNew.title}</p>
+      {whatsNew.highlights && whatsNew.highlights.length > 0 && (
+        <ul className="space-y-1 flex-1">
+          {whatsNew.highlights.map((highlight, i) => (
+            <li key={i} className="text-xs text-zinc-300 flex items-start gap-2">
+              <span className="text-orange-500/70 mt-0.5">•</span>
+              <span>{highlight}</span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+// Compact System Overview (server mode - full stats)
+function CompactOverview({
+  data,
+  loading,
+  onRefresh,
+}: {
+  data: DashboardData;
+  loading: boolean;
+  onRefresh: () => void;
+}) {
+  const stats = [
+    { label: 'Version', value: `v${data.system.version}` },
+    { label: 'Projects', value: formatNumber(data.content.projects) },
+    { label: 'Deployments', value: formatNumber(data.hosting.publishedDeployments) },
+    { label: 'Traffic/h', value: formatNumber(data.traffic.requestsLastHour) },
+    { label: 'Traffic/d', value: formatNumber(data.traffic.requestsLastDay) },
+    { label: 'Errors', value: formatNumber(data.traffic.errorCount), highlight: data.traffic.errorCount > 0 },
+    { label: 'Memory', value: formatBytes(data.system.memoryUsed) },
+    { label: 'Uptime', value: formatUptime(data.system.uptime) },
+  ];
+
+  const half = Math.ceil(stats.length / 2);
+  const leftColumn = stats.slice(0, half);
+  const rightColumn = stats.slice(half);
+
+  return (
+    <div className="bg-zinc-900/30 rounded-xl border border-zinc-800 p-4 flex flex-col">
+      <div className="flex items-center justify-between mb-3">
+        <h3 className="text-sm font-medium text-zinc-300">System Overview</h3>
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={onRefresh}
+          disabled={loading}
+          className="h-7 px-2"
+        >
+          <RefreshCw className={`w-3.5 h-3.5 ${loading ? 'animate-spin' : ''}`} />
+        </Button>
+      </div>
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-1.5 flex-1 content-start">
+        <div className="space-y-1.5">
+          {leftColumn.map((stat) => (
+            <div key={stat.label} className="flex items-center justify-between">
+              <span className="text-xs text-zinc-500">{stat.label}</span>
+              <span className={`text-sm font-medium ${stat.highlight ? 'text-yellow-500' : 'text-zinc-200'}`}>
+                {stat.value}
+              </span>
+            </div>
+          ))}
+        </div>
+        <div className="space-y-1.5">
+          {rightColumn.map((stat) => (
+            <div key={stat.label} className="flex items-center justify-between">
+              <span className="text-xs text-zinc-500">{stat.label}</span>
+              <span className={`text-sm font-medium ${stat.highlight ? 'text-yellow-500' : 'text-zinc-200'}`}>
+                {stat.value}
+              </span>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// Browser mode Overview (subset of stats)
+function BrowserOverview({
+  data,
+  loading,
+  onRefresh,
+}: {
+  data: BrowserDashboardData;
+  loading: boolean;
+  onRefresh: () => void;
+}) {
+  const stats = [
+    { label: 'Version', value: `v${pkg.version}` },
+    { label: 'Projects', value: formatNumber(data.content.projects) },
+    { label: 'Templates', value: formatNumber(data.content.templates) },
+    { label: 'Skills', value: formatNumber(data.content.skills) },
+  ];
+
+  const half = Math.ceil(stats.length / 2);
+  const leftColumn = stats.slice(0, half);
+  const rightColumn = stats.slice(half);
+
+  return (
+    <div className="bg-zinc-900/30 rounded-xl border border-zinc-800 p-4 flex flex-col">
+      <div className="flex items-center justify-between mb-3">
+        <h3 className="text-sm font-medium text-zinc-300">Content Overview</h3>
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={onRefresh}
+          disabled={loading}
+          className="h-7 px-2"
+        >
+          <RefreshCw className={`w-3.5 h-3.5 ${loading ? 'animate-spin' : ''}`} />
+        </Button>
+      </div>
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-1.5 flex-1 content-start">
+        <div className="space-y-1.5">
+          {leftColumn.map((stat) => (
+            <div key={stat.label} className="flex items-center justify-between">
+              <span className="text-xs text-zinc-500">{stat.label}</span>
+              <span className="text-sm font-medium text-zinc-200">{stat.value}</span>
+            </div>
+          ))}
+        </div>
+        <div className="space-y-1.5">
+          {rightColumn.map((stat) => (
+            <div key={stat.label} className="flex items-center justify-between">
+              <span className="text-xs text-zinc-500">{stat.label}</span>
+              <span className="text-sm font-medium text-zinc-200">{stat.value}</span>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+// Recent Projects Card
+function RecentProjectsCard({
+  projects,
+  onNavigate,
+  onProjectSelect,
+}: {
+  projects: DashboardData['recentProjects'] | BrowserDashboardData['recentProjects'];
+  onNavigate?: (view: string) => void;
+  onProjectSelect?: (projectId: string) => void;
+}) {
+  const handleViewAll = (e: React.MouseEvent) => {
+    if (!isServerMode && onNavigate) {
+      e.preventDefault();
+      onNavigate('projects');
+    }
+  };
+
+  const handleProjectClick = (e: React.MouseEvent, projectId: string) => {
+    if (!isServerMode && onProjectSelect) {
+      e.preventDefault();
+      onProjectSelect(projectId);
+    }
+  };
+
+  const viewAllHref = isServerMode ? '/admin/projects' : '#';
+
+  return (
+    <div className="bg-zinc-900/30 rounded-xl border border-zinc-800 p-4 flex flex-col">
+      <div className="flex items-center justify-between mb-3">
+        <div className="flex items-center gap-2">
+          <FolderOpen className="w-4 h-4 text-orange-500" />
+          <h3 className="text-sm font-medium text-zinc-300">Recent Projects</h3>
+        </div>
+        <Link
+          href={viewAllHref}
+          onClick={handleViewAll}
+          className="text-xs text-zinc-500 hover:text-zinc-300 flex items-center gap-0.5"
+        >
+          View all
+          <ChevronRight className="w-3 h-3" />
+        </Link>
+      </div>
+      {projects.length === 0 ? (
+        <p className="text-xs text-zinc-500 text-center py-2 flex-1 flex items-center justify-center">
+          No projects yet
+        </p>
+      ) : (
+        <div className="space-y-1.5 flex-1">
+          {projects.slice(0, 3).map((project) => (
+            <Link
+              key={project.id}
+              href={isServerMode ? `/admin/projects?open=${project.id}` : '#'}
+              onClick={(e) => handleProjectClick(e, project.id)}
+              className="flex items-center justify-between text-xs py-1.5 px-2 bg-zinc-900/50 rounded hover:bg-zinc-800/50 transition-colors"
+            >
+              <span className="text-zinc-300 truncate flex-1 mr-2">{project.name}</span>
+              <span className="text-zinc-500 shrink-0 flex items-center gap-1">
+                <Clock className="w-3 h-3" />
+                {formatRelativeTime(project.updatedAt)}
+              </span>
+            </Link>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// Recent Deployments Card
+function RecentDeploymentsCard({ deployments }: { deployments: DashboardData['recentDeployments'] }) {
+  return (
+    <div className="bg-zinc-900/30 rounded-xl border border-zinc-800 p-4 flex flex-col">
+      <div className="flex items-center justify-between mb-3">
+        <div className="flex items-center gap-2">
+          <Globe className="w-4 h-4 text-orange-500" />
+          <h3 className="text-sm font-medium text-zinc-300">Recent Deployments</h3>
+        </div>
+        <Link
+          href="/admin/deployments"
+          className="text-xs text-zinc-500 hover:text-zinc-300 flex items-center gap-0.5"
+        >
+          View all
+          <ChevronRight className="w-3 h-3" />
+        </Link>
+      </div>
+      {deployments.length === 0 ? (
+        <p className="text-xs text-zinc-500 text-center py-2 flex-1 flex items-center justify-center">
+          No deployments yet
+        </p>
+      ) : (
+        <div className="space-y-1.5 flex-1">
+          {deployments.slice(0, 3).map((deployment) => (
+            <Link
+              key={deployment.id}
+              href={`/admin/deployments?open=${deployment.id}`}
+              className="flex items-center justify-between text-xs py-1.5 px-2 bg-zinc-900/50 rounded hover:bg-zinc-800/50 transition-colors"
+            >
+              <div className="flex items-center gap-2 min-w-0 flex-1">
+                <span
+                  className={`w-1.5 h-1.5 rounded-full shrink-0 ${
+                    deployment.enabled ? 'bg-green-500' : 'bg-zinc-500'
+                  }`}
+                />
+                <span className="text-zinc-300 truncate">{deployment.name}</span>
+              </div>
+              <span className="text-zinc-500 shrink-0 flex items-center gap-1">
+                <Clock className="w-3 h-3" />
+                {formatRelativeTime(deployment.updatedAt)}
+              </span>
+            </Link>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// Compact Top Deployments & Errors
+function TrafficLists({ data }: { data: DashboardData }) {
+  return (
+    <div className="grid grid-cols-1 lg:grid-cols-2 gap-4">
+      {/* Top Deployments */}
+      <div className="bg-zinc-900/30 rounded-xl border border-zinc-800 p-4 flex flex-col">
+        <div className="flex items-center gap-2 mb-3">
+          <Globe className="w-4 h-4 text-orange-500" />
+          <h3 className="text-sm font-medium text-zinc-300">Top Deployments (24h)</h3>
+        </div>
+        {data.traffic.topDeployments.length === 0 ? (
+          <p className="text-xs text-zinc-500 text-center py-2 flex-1 flex items-center justify-center">
+            No traffic recorded yet
+          </p>
+        ) : (
+          <div className="space-y-1.5 flex-1">
+            {data.traffic.topDeployments.slice(0, 5).map((deployment, i) => (
+              <div
+                key={deployment.deploymentId}
+                className="flex items-center justify-between text-xs py-1 px-2 bg-zinc-900/50 rounded"
+              >
+                <div className="flex items-center gap-2 min-w-0">
+                  <span className="text-zinc-500 w-4">{i + 1}.</span>
+                  <span className="text-zinc-300 truncate">{deployment.deploymentName}</span>
+                </div>
+                <span className="text-zinc-500 shrink-0">{formatNumber(deployment.count)}</span>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {/* Recent Errors */}
+      <div className="bg-zinc-900/30 rounded-xl border border-zinc-800 p-4 flex flex-col">
+        <div className="flex items-center gap-2 mb-3">
+          <AlertTriangle className="w-4 h-4 text-orange-500" />
+          <h3 className="text-sm font-medium text-zinc-300">Recent Errors</h3>
+        </div>
+        {data.traffic.recentErrors.length === 0 ? (
+          <p className="text-xs text-zinc-500 text-center py-2 flex-1 flex items-center justify-center">
+            No errors recorded
+          </p>
+        ) : (
+          <div className="space-y-1.5 flex-1">
+            {data.traffic.recentErrors.slice(0, 5).map((error, i) => (
+              <div
+                key={`${error.deploymentId}-${error.path}-${i}`}
+                className="flex items-center justify-between text-xs py-1 px-2 bg-zinc-900/50 rounded"
+              >
+                <div className="flex items-center gap-2 min-w-0">
+                  <span
+                    className={`font-mono px-1 py-0.5 rounded text-[10px] ${
+                      error.statusCode >= 500
+                        ? 'bg-red-500/20 text-red-400'
+                        : 'bg-yellow-500/20 text-yellow-400'
+                    }`}
+                  >
+                    {error.statusCode}
+                  </span>
+                  <span className="text-zinc-400 truncate max-w-[140px]">{error.path}</span>
+                </div>
+                <span className="text-zinc-500 shrink-0 text-[10px]">
+                  {new Date(error.timestamp).toLocaleTimeString([], {
+                    hour: '2-digit',
+                    minute: '2-digit',
+                  })}
+                </span>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface DashboardViewProps {
+  workspaceId?: string;
+  onNavigate?: (view: string) => void;
+  onProjectSelect?: (projectId: string) => void;
+  onStartTour?: () => void;
+}
+
+// Fetch workspace-scoped data for non-admin server mode users
+async function fetchWorkspaceData(workspaceId: string): Promise<BrowserDashboardData> {
+  const response = await fetch(`/api/w/${workspaceId}/sync/status`);
+  if (!response.ok) throw new Error('Failed to fetch workspace data');
+  const data = await response.json();
+  const whatsNew = await fetchWhatsNew();
+
+  return {
+    content: {
+      projects: data.summary?.projectCount || 0,
+      templates: data.summary?.templateCount || 0,
+      skills: data.summary?.skillCount || 0,
+    },
+    whatsNew,
+    recentProjects: (data.projects || [])
+      .sort((a: { updatedAt: string }, b: { updatedAt: string }) => new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime())
+      .slice(0, 3)
+      .map((p: { id: string; name: string; updatedAt: string }) => ({
+        id: p.id,
+        name: p.name,
+        description: null,
+        updatedAt: p.updatedAt,
+      })),
+  };
+}
+
+export function DashboardView({ workspaceId, onNavigate, onProjectSelect, onStartTour }: DashboardViewProps) {
+  const router = useRouter();
+  // Server mode admin data
+  const [serverData, setServerData] = useState<DashboardData | null>(null);
+  // Browser mode / workspace mode data
+  const [browserData, setBrowserData] = useState<BrowserDashboardData | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchData = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      if (isServerMode && workspaceId) {
+        // Server mode with workspace: use workspace-scoped data
+        const result = await fetchWorkspaceData(workspaceId);
+        setBrowserData(result);
+      } else if (isServerMode) {
+        // Server mode without workspace (legacy admin path)
+        const response = await fetch('/api/admin/dashboard');
+        if (!response.ok) throw new Error('Failed to fetch dashboard data');
+        const result = await response.json();
+        setServerData(result);
+      } else {
+        // Browser mode: fetch from IndexedDB
+        const result = await fetchBrowserModeData();
+        setBrowserData(result);
+      }
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Unknown error');
+    } finally {
+      setLoading(false);
+    }
+  }, [workspaceId]);
+
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+
+  const handleStartTour = useCallback(() => {
+    if (onStartTour) {
+      // Browser mode: use callback
+      onStartTour();
+    } else {
+      // Server mode: use router
+      router.push('/admin/projects?tour=start');
+    }
+  }, [router, onStartTour]);
+
+  const handleProjectSelect = useCallback((projectId: string) => {
+    if (!isServerMode && onProjectSelect) {
+      onProjectSelect(projectId);
+    }
+  }, [onProjectSelect]);
+
+  // Loading state
+  const hasData = !!serverData || !!browserData;
+  if (loading && !hasData) {
+    return (
+      <div className="h-full flex items-center justify-center">
+        <div className="text-center">
+          <Spinner size={32} color="#f97316" className="mx-auto" />
+          <p className="mt-3 text-sm text-zinc-400">Loading dashboard...</p>
+        </div>
+      </div>
+    );
+  }
+
+  // Error state
+  if (error && !hasData) {
+    return (
+      <div className="h-full flex items-center justify-center">
+        <div className="text-center">
+          <AlertTriangle className="w-8 h-8 text-red-500 mx-auto mb-2" />
+          <p className="text-zinc-400 text-sm">{error}</p>
+          <Button variant="outline" size="sm" onClick={fetchData} className="mt-4">
+            Retry
+          </Button>
+        </div>
+      </div>
+    );
+  }
+
+  if (!hasData) return null;
+
+  // Server mode admin render (full system dashboard)
+  if (isServerMode && serverData) {
+    const hasWhatsNew = serverData.whatsNew?.highlights?.length > 0;
+
+    return (
+      <div className="h-full overflow-y-auto p-6">
+        {/* Quick Actions */}
+        <QuickActionsBar onStartTour={handleStartTour} />
+
+        {/* Row 1: System Overview + What's New */}
+        <div className="grid grid-cols-1 lg:grid-cols-2 gap-4 mb-4 [&>*]:min-h-[160px]">
+          <CompactOverview data={serverData} loading={loading} onRefresh={fetchData} />
+          {hasWhatsNew && <WhatsNewCard whatsNew={serverData.whatsNew} />}
+        </div>
+
+        {/* Row 2: Recent Projects + Recent Deployments */}
+        <div className="grid grid-cols-1 lg:grid-cols-2 gap-4 mb-4 [&>*]:min-h-[160px]">
+          <RecentProjectsCard projects={serverData.recentProjects} />
+          <RecentDeploymentsCard deployments={serverData.recentDeployments} />
+        </div>
+
+        {/* Row 3: Top Deployments + Recent Errors */}
+        <div className="[&>*>*]:min-h-[140px]">
+          <TrafficLists data={serverData} />
+        </div>
+      </div>
+    );
+  }
+
+  // Browser mode render OR server mode non-admin workspace render
+  if (browserData) {
+    const hasWhatsNew = browserData.whatsNew !== null;
+
+    return (
+      <div className="h-full overflow-y-auto p-6">
+        {/* Quick Actions */}
+        <QuickActionsBar onStartTour={handleStartTour} onNavigate={onNavigate} />
+
+        {/* Row 1: Content Overview + What's New */}
+        <div className="grid grid-cols-1 lg:grid-cols-2 gap-4 mb-4 [&>*]:min-h-[160px]">
+          <BrowserOverview data={browserData} loading={loading} onRefresh={fetchData} />
+          {hasWhatsNew && (
+            <WhatsNewCard
+              whatsNew={browserData.whatsNew!}
+              onNavigate={onNavigate}
+            />
+          )}
+        </div>
+
+        {/* Row 2: Recent Projects (no Deployments in browser mode) */}
+        <div className="mb-4 lg:w-1/2">
+          <RecentProjectsCard
+            projects={browserData.recentProjects}
+            onNavigate={onNavigate}
+            onProjectSelect={handleProjectSelect}
+          />
+        </div>
+      </div>
+    );
+  }
+
+  return null;
+}

components/views/deployments-view.tsx

@@ -0,0 +1,790 @@
+'use client';
+
+import React, { useState, useEffect, useMemo, useRef } from 'react';
+import { Deployment, Project } from '@/lib/vfs/types';
+import { vfs } from '@/lib/vfs';
+import { getLoginUrl } from '@/lib/config/storage';
+import { getSyncManager } from '@/lib/vfs/sync-manager';
+import { DeploymentCard } from '../deployment-card';
+import { DeploymentSettingsModal } from '../deployment-settings';
+import { ServerSettingsModal } from '../server-settings';
+import { CreateDeploymentModal } from '../create-deployment-modal';
+import { AnalyticsDashboard } from '../analytics-dashboard';
+import { TemplateExportDialog } from '../templates/template-export-dialog';
+import { ProjectSwapDialog } from '../project-swap-dialog';
+import { Globe, Plus, Search, ArrowUpDown } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Spinner } from '@/components/ui/spinner';
+import { Input } from '@/components/ui/input';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components/ui/select';
+import { toast } from 'sonner';
+import { logger } from '@/lib/utils';
+import { track } from '@/lib/telemetry';
+import { usePagination } from '@/lib/hooks/use-pagination';
+import { Pagination, PaginationRange } from '@/components/ui/pagination';
+
+type SortOption = 'updated' | 'created' | 'name' | 'published';
+
+interface DeploymentsViewProps {
+  onProjectSelect: (project: Project) => void;
+  workspaceId?: string;
+}
+
+export function DeploymentsView({ onProjectSelect, workspaceId }: DeploymentsViewProps) {
+  const apiBase = workspaceId ? `/api/w/${workspaceId}` : '/api';
+  const [deployments, setDeployments] = useState<Deployment[]>([]);
+  const [projects, setProjects] = useState<Project[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [publishingStates, setPublishingStates] = useState<Record<string, boolean>>({});
+  const [selectedDeployment, setSelectedDeployment] = useState<Deployment | null>(null);
+  const [showSettingsModal, setShowSettingsModal] = useState(false);
+  const [showServerSettingsModal, setShowServerSettingsModal] = useState(false);
+  const [showAnalyticsModal, setShowAnalyticsModal] = useState(false);
+  const [showCreateModal, setShowCreateModal] = useState(false);
+  const [showTemplateExportModal, setShowTemplateExportModal] = useState(false);
+  const [templateExportDeployment, setTemplateExportDeployment] = useState<Deployment | null>(null);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [sortBy, setSortBy] = useState<SortOption>('updated');
+  const [swapDialogState, setSwapDialogState] = useState<{
+    deploymentId: string;
+    deploymentName: string;
+    currentProjectId: string;
+    newProjectId: string;
+    newProjectName: string;
+    pendingSettings: Partial<Deployment>;
+  } | null>(null);
+  const isServerMode = process.env.NEXT_PUBLIC_SERVER_MODE === 'true';
+
+  useEffect(() => {
+    loadData();
+  }, []);
+
+  const loadData = async () => {
+    try {
+      setLoading(true);
+
+      if (!isServerMode) {
+        setLoading(false);
+        return;
+      }
+
+      const [deploymentsResponse, projectsResponse] = await Promise.all([
+        fetch(`${apiBase}/deployments`),
+        fetch(`${apiBase}/projects?fields=id,name`), // Only fetch id and name fields
+      ]);
+
+      // Redirect to login if unauthorized
+      if (deploymentsResponse.status === 401 || projectsResponse.status === 401) {
+        window.location.href = getLoginUrl();
+        return;
+      }
+
+      if (!deploymentsResponse.ok) {
+        throw new Error('Failed to fetch deployments');
+      }
+      if (!projectsResponse.ok) {
+        throw new Error('Failed to fetch projects');
+      }
+
+      const [fetchedDeployments, fetchedProjects] = await Promise.all([
+        deploymentsResponse.json(),
+        projectsResponse.json(),
+      ]);
+
+      setDeployments(fetchedDeployments);
+      setProjects(fetchedProjects);
+    } catch (error) {
+      logger.error('[DeploymentsView] Failed to load data:', error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  // Helper function to update a single deployment in state (optimistic updates)
+  const updateDeploymentInState = (deploymentId: string, updates: Partial<Deployment>) => {
+    setDeployments(prevDeployments =>
+      prevDeployments.map(deployment =>
+        deployment.id === deploymentId ? { ...deployment, ...updates } : deployment
+      )
+    );
+  };
+
+  const handleOpenSettings = (deployment: Deployment) => {
+    setSelectedDeployment(deployment);
+    setShowSettingsModal(true);
+  };
+
+  const handleOpenServerSettings = (deployment: Deployment) => {
+    setSelectedDeployment(deployment);
+    setShowServerSettingsModal(true);
+  };
+
+  const handleViewAnalytics = (deployment: Deployment) => {
+    setSelectedDeployment(deployment);
+    setShowAnalyticsModal(true);
+  };
+
+  const handleEditProject = async (deployment: Deployment) => {
+    try {
+      await vfs.init();
+      const project = await vfs.getProject(deployment.projectId);
+      if (!project) {
+        toast.error('Project not found in local storage');
+        return;
+      }
+      onProjectSelect(project);
+    } catch (error) {
+      logger.error('[DeploymentsView] Failed to load project:', error);
+      toast.error('Failed to load project');
+    }
+  };
+
+  const [templateExportProject, setTemplateExportProject] = useState<Project | null>(null);
+
+  const handleExportAsTemplate = async (deployment: Deployment) => {
+    try {
+      await vfs.init();
+      const project = await vfs.getProject(deployment.projectId);
+      if (!project) {
+        toast.error('Project not found in local storage');
+        return;
+      }
+      setTemplateExportDeployment(deployment);
+      setTemplateExportProject(project);
+      setShowTemplateExportModal(true);
+    } catch (error) {
+      logger.error('[DeploymentsView] Failed to load project for template export:', error);
+      toast.error('Failed to load project');
+    }
+  };
+
+  const handleSaveSettings = async (settings: Partial<Deployment>) => {
+    if (!selectedDeployment) return;
+
+    try {
+      // If projectId changed in server mode, show swap dialog for conflict analysis
+      const projectIdChanged = settings.projectId && settings.projectId !== selectedDeployment.projectId;
+      if (projectIdChanged && isServerMode && selectedDeployment.publishedAt) {
+        const newProject = projects.find(p => p.id === settings.projectId);
+        setSwapDialogState({
+          deploymentId: selectedDeployment.id,
+          deploymentName: selectedDeployment.name,
+          currentProjectId: selectedDeployment.projectId,
+          newProjectId: settings.projectId!,
+          newProjectName: newProject?.name || 'Unknown',
+          pendingSettings: settings,
+        });
+        return; // Don't save yet — swap dialog will handle it
+      }
+
+      if (projectIdChanged) {
+        // Non-server mode or first deploy: update directly
+        const deploymentResponse = await fetch(`${apiBase}/deployments/${selectedDeployment.id}`, {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ projectId: settings.projectId }),
+        });
+
+        if (!deploymentResponse.ok) {
+          const error = await deploymentResponse.json();
+          throw new Error(error.error || 'Failed to update project');
+        }
+      }
+
+      // Save publishing settings (exclude projectId — handled above)
+      const { projectId: _projectId, ...publishSettings } = settings;
+
+      const response = await fetch(`${apiBase}/deployments/${selectedDeployment.id}/settings`, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(publishSettings),
+      });
+
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || 'Failed to save settings');
+      }
+
+      const result = await response.json();
+
+      // Fire only on the empty -> set transition, never on every save and
+      // never with the domain value itself.
+      if (!selectedDeployment.customDomain && settings.customDomain) {
+        track('custom_domain_set');
+      }
+
+      // Update local deployment state in the selected deployment modal
+      setSelectedDeployment({
+        ...selectedDeployment,
+        ...settings,
+        settingsVersion: result.settingsVersion,
+        lastPublishedVersion: result.lastPublishedVersion,
+      });
+
+      // Update the deployment in the main list (optimistic update - no full reload)
+      updateDeploymentInState(selectedDeployment.id, {
+        ...settings,
+        settingsVersion: result.settingsVersion,
+        updatedAt: new Date(),
+      });
+    } catch (error) {
+      logger.error('[DeploymentsView] Failed to save deployment settings:', error);
+      throw error;
+    }
+  };
+
+  const handleSwapComplete = async () => {
+    if (!swapDialogState) return;
+
+    // Swap + republish completed via the swap API.
+    // Now save any remaining publishing settings.
+    const { deploymentId, pendingSettings } = swapDialogState;
+    const { projectId: _projectId, ...publishSettings } = pendingSettings;
+
+    try {
+      const response = await fetch(`${apiBase}/deployments/${deploymentId}/settings`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(publishSettings),
+      });
+
+      if (response.ok) {
+        const result = await response.json();
+        updateDeploymentInState(deploymentId, {
+          ...pendingSettings,
+          settingsVersion: result.settingsVersion,
+          updatedAt: new Date(),
+          publishedAt: new Date(),
+        });
+      }
+    } catch (err) {
+      logger.error('[DeploymentsView] Failed to save settings after swap:', err);
+    }
+
+    setSwapDialogState(null);
+    setShowSettingsModal(false);
+    setSelectedDeployment(null);
+    toast.success('Project swapped and deployment republished');
+    await loadData();
+  };
+
+  const handlePublish = async (deploymentId: string) => {
+    const deployment = deployments.find(s => s.id === deploymentId);
+    if (!deployment) return;
+
+    if (!confirm('Publish this deployment with the current settings?')) {
+      return;
+    }
+
+    // Set publishing state
+    setPublishingStates(prev => ({ ...prev, [deploymentId]: true }));
+
+    let trackedRuntime = 'unknown';
+
+    try {
+      // First, sync files from IndexedDB to server
+      toast.info('Syncing project files...');
+
+      await vfs.init();
+      const project = await vfs.getProject(deployment.projectId);
+      if (!project) {
+        throw new Error('Project not found in local storage');
+      }
+
+      // Block publishing for terminal-mode runtimes (Python, Lua) — they can't be
+      // served as static sites. Use ZIP export instead.
+      const { isRuntimeBundled, getRuntimeConfig } = await import('@/lib/runtimes/registry');
+      const runtime = project.settings?.runtime;
+      trackedRuntime = runtime ?? 'unknown';
+      if (runtime && getRuntimeConfig(runtime).previewMode === 'terminal') {
+        throw new Error(`${getRuntimeConfig(runtime).label} projects cannot be published as static sites. Use ZIP export instead.`);
+      }
+
+      let files = await vfs.listFiles(deployment.projectId);
+
+      if (runtime && isRuntimeBundled(runtime)) {
+        // Always compile fresh — generated files may be stale or absent
+        // (e.g. user publishes without opening the preview first)
+        toast.info('Compiling project bundles...');
+        const { VirtualServer } = await import('@/lib/preview/virtual-server');
+        const vs = new VirtualServer(vfs as any, deployment.projectId, { runtime });
+        await vs.compileProject();
+        vs.cleanupBlobUrls();
+
+        const generatedFiles = vfs.getGeneratedFiles();
+        if (generatedFiles.length > 0) {
+          const withProjectId = generatedFiles.map(f => ({ ...f, projectId: deployment.projectId }));
+          files = [...files, ...withProjectId];
+        }
+      }
+
+      const syncManager = getSyncManager();
+
+      // Push project and files to server
+      const syncResult = await syncManager.pushProjectWithFiles(project, files);
+      if (!syncResult.success) {
+        throw new Error(syncResult.error || 'Failed to sync files to server');
+      }
+
+      // Sync backend features from IndexedDB to server
+      const adapter = await vfs.getStorageAdapter();
+      const edgeFunctions = adapter.listEdgeFunctions ? await adapter.listEdgeFunctions(deployment.projectId) : [];
+      const serverFunctions = adapter.listServerFunctions ? await adapter.listServerFunctions(deployment.projectId) : [];
+      const secrets = adapter.listSecrets ? await adapter.listSecrets(deployment.projectId) : [];
+      const scheduledFunctions = adapter.listScheduledFunctions ? await adapter.listScheduledFunctions(deployment.projectId) : [];
+
+      if (edgeFunctions.length > 0 || serverFunctions.length > 0 ||
+          secrets.length > 0 || scheduledFunctions.length > 0) {
+        toast.info('Syncing backend features...');
+        const featuresSyncResult = await syncManager.pushBackendFeatures(deployment.projectId, {
+          edgeFunctions,
+          serverFunctions,
+          secrets,
+          scheduledFunctions,
+        });
+        if (!featuresSyncResult.success) {
+          throw new Error(featuresSyncResult.error || 'Failed to sync backend features');
+        }
+      }
+
+      toast.info('Building deployment...');
+
+      // Call publish API to trigger build
+      const response = await fetch(`${apiBase}/deployments/${deploymentId}/publish`, {
+        method: 'POST',
+      });
+
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || 'Failed to publish');
+      }
+
+      const result = await response.json();
+
+      track('deployment_publish', {
+        runtime: runtime ?? 'unknown',
+        result: 'success',
+        has_custom_domain: !!deployment.customDomain,
+      });
+
+      toast.success(`Deployment published! ${result.filesWritten} files written.`);
+
+      // Update state optimistically with publish data
+      updateDeploymentInState(deploymentId, {
+        lastPublishedVersion: result.lastPublishedVersion,
+        publishedAt: new Date(),
+        updatedAt: new Date(),
+        databaseEnabled: true,
+        ...(result.slug && { slug: result.slug }),
+      });
+
+      // Clear publishing state immediately after successful publish
+      setPublishingStates(prev => ({ ...prev, [deploymentId]: false }));
+    } catch (error) {
+      logger.error('Failed to publish:', error);
+      track('deployment_publish', {
+        runtime: trackedRuntime,
+        result: 'fail',
+        has_custom_domain: !!deployment.customDomain,
+      });
+      toast.error(error instanceof Error ? error.message : 'Failed to publish. Please try again.');
+      // Clear publishing state on error
+      setPublishingStates(prev => ({ ...prev, [deploymentId]: false }));
+    }
+  };
+
+  const handleDeploymentThumbnailChange = async (deploymentId: string, image: string | undefined) => {
+    try {
+      const response = await fetch(`${apiBase}/deployments/${deploymentId}/thumbnail`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ previewImage: image ?? null }),
+      });
+      if (!response.ok) throw new Error('Failed to update thumbnail');
+
+      updateDeploymentInState(deploymentId, {
+        previewImage: image,
+        previewUpdatedAt: image ? new Date() : undefined,
+      });
+    } catch (err) {
+      logger.error('[DeploymentsView] Failed to update deployment thumbnail:', err);
+      toast.error('Failed to update thumbnail');
+    }
+  };
+
+  const handleDisable = async (deploymentId: string) => {
+    const deployment = deployments.find(s => s.id === deploymentId);
+    if (!deployment) return;
+
+    if (!confirm('Disable this deployment? It will no longer be publicly accessible.')) {
+      return;
+    }
+
+    try {
+      const response = await fetch(`${apiBase}/deployments/${deploymentId}`, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          enabled: false,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || 'Failed to disable deployment');
+      }
+
+      // Update state optimistically (no full reload)
+      updateDeploymentInState(deploymentId, {
+        enabled: false,
+        updatedAt: new Date(),
+      });
+    } catch (error) {
+      logger.error('Failed to disable deployment:', error);
+      alert('Failed to disable deployment. Please try again.');
+    }
+  };
+
+  const handleEnable = async (deploymentId: string) => {
+    const deployment = deployments.find(s => s.id === deploymentId);
+    if (!deployment) return;
+
+    try {
+      const response = await fetch(`${apiBase}/deployments/${deploymentId}`, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          enabled: true,
+        }),
+      });
+
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || 'Failed to enable deployment');
+      }
+
+      // Update state optimistically (no full reload)
+      updateDeploymentInState(deploymentId, {
+        enabled: true,
+        updatedAt: new Date(),
+      });
+    } catch (error) {
+      logger.error('Failed to enable deployment:', error);
+      alert('Failed to enable deployment. Please try again.');
+    }
+  };
+
+  const handleDelete = async (deploymentId: string) => {
+    const deployment = deployments.find(s => s.id === deploymentId);
+    if (!deployment) return;
+
+    if (!confirm(`Delete deployment "${deployment.name}"? This cannot be undone.`)) {
+      return;
+    }
+
+    try {
+      const response = await fetch(`${apiBase}/deployments/${deploymentId}`, {
+        method: 'DELETE',
+      });
+
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || 'Failed to delete deployment');
+      }
+
+      track('deployment_delete');
+
+      await loadData();
+    } catch (error) {
+      logger.error('Failed to delete deployment:', error);
+      alert('Failed to delete deployment. Please try again.');
+    }
+  };
+
+  const handleCreateDeployment = async (data: { projectId: string; name: string; slug?: string }) => {
+    try {
+      const response = await fetch(`${apiBase}/deployments`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(data),
+      });
+
+      if (!response.ok) {
+        const error = await response.json();
+        throw new Error(error.error || 'Failed to create deployment');
+      }
+
+      track('deployment_create');
+
+      await loadData();
+      setShowCreateModal(false);
+    } catch (error) {
+      logger.error('Failed to create deployment:', error);
+      throw error;
+    }
+  };
+
+  // Filter and sort deployments
+  const filteredAndSortedDeployments = useMemo(() => {
+    let filtered = deployments;
+
+    // Apply search filter
+    if (searchQuery) {
+      const query = searchQuery.toLowerCase();
+      filtered = deployments.filter(deployment => {
+        const project = projects.find(p => p.id === deployment.projectId);
+        return (
+          deployment.name.toLowerCase().includes(query) ||
+          deployment.slug?.toLowerCase().includes(query) ||
+          project?.name.toLowerCase().includes(query)
+        );
+      });
+    }
+
+    // Apply sorting
+    const sorted = [...filtered].sort((a, b) => {
+      switch (sortBy) {
+        case 'name':
+          return a.name.localeCompare(b.name);
+        case 'created':
+          return new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime();
+        case 'published':
+          if (!a.publishedAt && !b.publishedAt) return 0;
+          if (!a.publishedAt) return 1;
+          if (!b.publishedAt) return -1;
+          return new Date(b.publishedAt).getTime() - new Date(a.publishedAt).getTime();
+        case 'updated':
+        default:
+          return new Date(b.updatedAt).getTime() - new Date(a.updatedAt).getTime();
+      }
+    });
+
+    return sorted;
+  }, [deployments, projects, searchQuery, sortBy]);
+
+  const deploymentsPagination = usePagination(filteredAndSortedDeployments, {
+    perPage: 24,
+    resetOn: [searchQuery, sortBy],
+  });
+  const listScrollRef = useRef<HTMLDivElement | null>(null);
+
+  if (!isServerMode) {
+    return (
+      <div className="h-full flex items-center justify-center">
+        <div className="text-center text-muted-foreground">
+          <p>Deployments feature is only available in Server Mode</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (loading) {
+    return (
+      <div className="h-full flex items-center justify-center">
+        <div className="text-center">
+          <Spinner size={48} color="#f97316" className="mx-auto" />
+          <p className="mt-4">Loading deployments...</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <div className="h-full flex flex-col">
+        {/* Toolbar */}
+        <div className="pt-4 px-4 pb-3 sm:pt-6 sm:px-6 sm:pb-3 shrink-0">
+          <div className="mx-auto max-w-7xl flex flex-col sm:flex-row gap-3">
+            {/* Search */}
+            <div className="relative flex-1">
+              <Search className="absolute left-3 top-1/2 transform -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+              <Input
+                placeholder="Search deployments..."
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                className="pl-9"
+              />
+            </div>
+
+            {/* Controls */}
+            <div className="flex items-center gap-2">
+              {/* Sort */}
+              <Popover>
+                <PopoverTrigger asChild>
+                  <Button variant="outline" size="sm" className="gap-2">
+                    <ArrowUpDown className="h-4 w-4" />
+                    <span className="hidden sm:inline">Sort</span>
+                  </Button>
+                </PopoverTrigger>
+                <PopoverContent className="w-48" align="end">
+                  <div className="space-y-2">
+                    <h4 className="font-semibold text-sm">Sort by</h4>
+                    <Select value={sortBy} onValueChange={(value) => setSortBy(value as SortOption)}>
+                      <SelectTrigger>
+                        <SelectValue />
+                      </SelectTrigger>
+                      <SelectContent>
+                        <SelectItem value="updated">Last Updated</SelectItem>
+                        <SelectItem value="published">Last Published</SelectItem>
+                        <SelectItem value="created">Date Created</SelectItem>
+                        <SelectItem value="name">Name</SelectItem>
+                      </SelectContent>
+                    </Select>
+                  </div>
+                </PopoverContent>
+              </Popover>
+
+              {/* New Deployment */}
+              <Button onClick={() => setShowCreateModal(true)} size="sm" className="gap-2">
+                <Plus className="h-4 w-4" />
+                <span>New</span>
+              </Button>
+            </div>
+          </div>
+        </div>
+
+        {/* Deployments Grid/List */}
+        <div ref={listScrollRef} className="flex-1 px-4 pt-3 pb-4 sm:px-6 sm:pt-3 sm:pb-6 overflow-auto">
+          <div className="mx-auto max-w-7xl">
+            {filteredAndSortedDeployments.length === 0 ? (
+              <div className="flex flex-col items-center justify-center py-16 text-center">
+                <Globe className="h-16 w-16 text-muted-foreground mb-4" />
+                {deployments.length === 0 ? (
+                  <>
+                    <h2 className="text-xl font-semibold mb-2">No Deployments Yet</h2>
+                    <p className="text-muted-foreground mb-4 max-w-md">
+                      Create your first deployment by clicking the "New" button above.
+                      Deployments let you publish projects and manage their public settings independently.
+                    </p>
+                  </>
+                ) : (
+                  <>
+                    <h2 className="text-xl font-semibold mb-2">No deployments found</h2>
+                    <p className="text-muted-foreground mb-4 max-w-md">
+                      Try adjusting your search or filter criteria
+                    </p>
+                  </>
+                )}
+              </div>
+            ) : (
+              <>
+                <PaginationRange
+                  total={deploymentsPagination.total}
+                  rangeStart={deploymentsPagination.rangeStart}
+                  rangeEnd={deploymentsPagination.rangeEnd}
+                  totalPages={deploymentsPagination.totalPages}
+                  className="mb-2"
+                />
+                <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+                  {deploymentsPagination.pageItems.map((deployment) => {
+                    const project = projects.find(p => p.id === deployment.projectId);
+                    return (
+                      <DeploymentCard
+                        key={deployment.id}
+                        deployment={deployment}
+                        project={project}
+                        isPublishing={publishingStates[deployment.id] || false}
+                        onOpenSettings={handleOpenSettings}
+                        onOpenServerSettings={handleOpenServerSettings}
+                        onViewAnalytics={handleViewAnalytics}
+                        onEditProject={handleEditProject}
+                        onPublish={handlePublish}
+                        onDisable={handleDisable}
+                        onEnable={handleEnable}
+                        onDelete={handleDelete}
+                        onExportAsTemplate={handleExportAsTemplate}
+                        onThumbnailChange={handleDeploymentThumbnailChange}
+                      />
+                    );
+                  })}
+                </div>
+                <Pagination
+                  page={deploymentsPagination.page}
+                  totalPages={deploymentsPagination.totalPages}
+                  onPageChange={deploymentsPagination.setPage}
+                  scrollTarget={listScrollRef}
+                />
+              </>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {selectedDeployment && (
+        <>
+          <DeploymentSettingsModal
+            deployment={selectedDeployment}
+            projects={projects}
+            isOpen={showSettingsModal}
+            onClose={() => {
+              setShowSettingsModal(false);
+              setSelectedDeployment(null);
+            }}
+            onSave={handleSaveSettings}
+          />
+
+          <ServerSettingsModal
+            deployment={selectedDeployment}
+            isOpen={showServerSettingsModal}
+            onClose={() => {
+              setShowServerSettingsModal(false);
+              setSelectedDeployment(null);
+            }}
+            workspaceId={workspaceId}
+          />
+
+          <AnalyticsDashboard
+            deployment={selectedDeployment}
+            isOpen={showAnalyticsModal}
+            onClose={() => {
+              setShowAnalyticsModal(false);
+              setSelectedDeployment(null);
+            }}
+          />
+        </>
+      )}
+
+      <CreateDeploymentModal
+        projects={projects}
+        isOpen={showCreateModal}
+        onClose={() => setShowCreateModal(false)}
+        onCreate={handleCreateDeployment}
+      />
+
+      <TemplateExportDialog
+        project={templateExportProject}
+        open={showTemplateExportModal}
+        onOpenChange={(open) => {
+          setShowTemplateExportModal(open);
+          if (!open) {
+            setTemplateExportDeployment(null);
+            setTemplateExportProject(null);
+          }
+        }}
+      />
+
+      {swapDialogState && (
+        <ProjectSwapDialog
+          isOpen={true}
+          onClose={() => setSwapDialogState(null)}
+          deploymentId={swapDialogState.deploymentId}
+          deploymentName={swapDialogState.deploymentName}
+          currentProjectId={swapDialogState.currentProjectId}
+          newProjectId={swapDialogState.newProjectId}
+          newProjectName={swapDialogState.newProjectName}
+          onSwapComplete={handleSwapComplete}
+          workspaceId={workspaceId}
+        />
+      )}
+    </>
+  );
+}

components/views/docs-view.tsx

@@ -0,0 +1,282 @@
+'use client';
+
+import React, { useState, useEffect, useRef, useCallback, Suspense } from 'react';
+import { useSearchParams } from 'next/navigation';
+import { MarkdownRenderer } from '@/components/markdown-renderer';
+import { TableOfContents } from '@/components/table-of-contents';
+import { useTableOfContents } from '@/lib/hooks/use-table-of-contents';
+import { AlertCircle } from 'lucide-react';
+import { Spinner } from '@/components/ui/spinner';
+import { DOCS_ITEMS } from '@/lib/constants/docs';
+
+function DocsViewContent() {
+  const searchParams = useSearchParams();
+  const docId = searchParams.get('doc') || 'overview';
+
+  const selectedDoc = DOCS_ITEMS.find(d => d.id === docId) || DOCS_ITEMS[0];
+  const [content, setContent] = useState<string>('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [activeId, setActiveId] = useState<string>('');
+  const [visibleIds, setVisibleIds] = useState<string[]>([]);
+
+  const isManualScrolling = useRef(false);
+  const scrollDebounceTimer = useRef<NodeJS.Timeout | null>(null);
+
+  const tocItems = useTableOfContents(content);
+
+  useEffect(() => {
+    async function loadDoc() {
+      setLoading(true);
+      setError(null);
+
+      try {
+        const response = await fetch(`/api/docs/${selectedDoc.file}`);
+        if (!response.ok) {
+          throw new Error(`Failed to load document: ${response.statusText}`);
+        }
+        const text = await response.text();
+        setContent(text);
+
+        // Scroll to hash if present in URL
+        setTimeout(() => {
+          if (window.location.hash) {
+            const element = document.getElementById(window.location.hash.slice(1));
+            if (element) {
+              element.scrollIntoView({ behavior: 'smooth' });
+            }
+          } else {
+            // Scroll to top if no hash
+            const contentArea = document.querySelector('.docs-content-area');
+            if (contentArea) {
+              contentArea.scrollTop = 0;
+            }
+          }
+        }, 100);
+      } catch (err) {
+        console.error('Failed to load doc:', err);
+        setError(err instanceof Error ? err.message : 'Failed to load document');
+        setContent('');
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    loadDoc();
+  }, [selectedDoc]);
+
+  // Handle TOC item clicks
+  const handleTocClick = useCallback((id: string) => {
+    // Set active immediately when user clicks
+    setActiveId(id);
+
+    // Immediately update visible IDs to include only the clicked item
+    // This prevents stale blue highlights during the scroll
+    setVisibleIds([id]);
+
+    // Disable auto-tracking during manual scroll
+    isManualScrolling.current = true;
+
+    // Re-enable auto-tracking after scroll animation completes
+    // and then trigger an immediate update
+    setTimeout(() => {
+      isManualScrolling.current = false;
+
+      // Trigger immediate recalculation of visible items after scroll completes
+      const scrollContainer = document.querySelector('.docs-content-area');
+      if (!scrollContainer) return;
+
+      const headings = document.querySelectorAll('.docs-content-area [data-heading-index]');
+      if (headings.length === 0) return;
+
+      const containerTop = scrollContainer.getBoundingClientRect().top;
+      const visible: string[] = [];
+
+      headings.forEach((heading) => {
+        const rect = heading.getBoundingClientRect();
+        const viewportTop = containerTop;
+        const viewportBottom = viewportTop + scrollContainer.clientHeight;
+
+        if (rect.top >= viewportTop && rect.bottom <= viewportBottom) {
+          const index = heading.getAttribute('data-heading-index');
+          if (index) {
+            visible.push(index);
+          }
+        }
+      });
+
+      setVisibleIds(visible);
+    }, 1000); // Smooth scroll takes ~500-800ms, add buffer
+  }, []);
+
+  // Scroll-based active section tracking with debouncing
+  useEffect(() => {
+    if (tocItems.length === 0) return;
+
+    const scrollContainer = document.querySelector('.docs-content-area');
+    if (!scrollContainer) return;
+
+    const updateActiveSection = () => {
+      // Skip if user is manually scrolling from TOC click
+      if (isManualScrolling.current) {
+        return;
+      }
+
+      // Select headings by data-heading-index attribute for unique identification
+      const headings = document.querySelectorAll('.docs-content-area [data-heading-index]');
+      if (headings.length === 0) return;
+
+      const containerTop = scrollContainer.getBoundingClientRect().top;
+
+      // Find the heading that's currently at the top of the viewport
+      let activeHeading = headings[0];
+      let minDistance = Infinity;
+
+      headings.forEach((heading) => {
+        const rect = heading.getBoundingClientRect();
+        const distance = Math.abs(rect.top - containerTop - 100); // 100px offset
+
+        if (rect.top - containerTop < 200 && distance < minDistance) {
+          minDistance = distance;
+          activeHeading = heading;
+        }
+      });
+
+      // Collect IDs of all headings in viewport
+      const visible: string[] = [];
+      headings.forEach((heading) => {
+        const rect = heading.getBoundingClientRect();
+        const viewportTop = containerTop;
+        const viewportBottom = viewportTop + scrollContainer.clientHeight;
+
+        // Check if heading is in viewport
+        if (rect.top >= viewportTop && rect.bottom <= viewportBottom) {
+          const index = heading.getAttribute('data-heading-index');
+          if (index) {
+            visible.push(index);
+          }
+        }
+      });
+
+      // Use data-heading-index as the unique identifier
+      const headingIndex = activeHeading?.getAttribute('data-heading-index');
+      if (headingIndex) {
+        setActiveId(headingIndex);
+      }
+
+      // Update visible IDs for TOC range highlighting
+      setVisibleIds(visible);
+    };
+
+    // Debounced scroll handler
+    const handleScroll = () => {
+      // Clear existing timer
+      if (scrollDebounceTimer.current) {
+        clearTimeout(scrollDebounceTimer.current);
+      }
+
+      // Set new timer - only update after scrolling stops for 50ms
+      scrollDebounceTimer.current = setTimeout(updateActiveSection, 50);
+    };
+
+    // Initial update - delay to ensure markdown heading indices are set
+    // Increase delay to 500ms to ensure MarkdownRenderer's useEffect completes
+    const timeout = setTimeout(() => {
+      updateActiveSection();
+    }, 500);
+
+    // Update on scroll with debouncing
+    scrollContainer.addEventListener('scroll', handleScroll);
+
+    return () => {
+      clearTimeout(timeout);
+      if (scrollDebounceTimer.current) {
+        clearTimeout(scrollDebounceTimer.current);
+      }
+      scrollContainer.removeEventListener('scroll', handleScroll);
+    };
+  }, [tocItems, content]);
+
+  const showToc = tocItems.length >= 3;
+
+  return (
+    <div className="h-full flex flex-col">
+      {/* Two-column layout: Content + TOC */}
+      <div className={`flex-1 overflow-hidden ${showToc ? 'lg:grid lg:grid-cols-[1fr_280px]' : ''}`}>
+        {/* Main Content Area - scrollable */}
+        <div className="h-full overflow-y-auto docs-content-area bg-background">
+          <div
+            className="p-6 sm:p-8 max-w-4xl mx-auto"
+            onClick={(e) => {
+              // Handle anchor link clicks
+              const target = e.target as HTMLElement;
+              if (target.tagName === 'A') {
+                const href = target.getAttribute('href');
+                if (href?.startsWith('#')) {
+                  e.preventDefault();
+                  const element = document.getElementById(href.slice(1));
+                  if (element) {
+                    element.scrollIntoView({ behavior: 'smooth' });
+                    window.history.pushState(null, '', href);
+                  }
+                }
+              }
+            }}
+          >
+          {loading && (
+            <div className="flex items-center justify-center h-screen">
+              <div className="text-center">
+                <Spinner size={48} className="mx-auto text-primary" />
+                <p className="mt-4 text-muted-foreground">Loading documentation...</p>
+              </div>
+            </div>
+          )}
+
+          {error && (
+            <div className="flex items-center gap-3 p-4 bg-destructive/10 border border-destructive/20 rounded-lg text-destructive">
+              <AlertCircle className="h-5 w-5 flex-shrink-0" />
+              <div>
+                <p className="font-semibold">Error loading document</p>
+                <p className="text-sm">{error}</p>
+              </div>
+            </div>
+          )}
+
+          {!loading && !error && content && (
+            <>
+              {/* Document Title */}
+              <div className="mb-6 pb-4 border-b">
+                <div className="flex items-center gap-3 mb-2">
+                  <selectedDoc.icon className="h-8 w-8 text-primary" />
+                  <h1 className="text-3xl font-bold">{selectedDoc.title}</h1>
+                </div>
+              </div>
+
+              {/* Markdown Content */}
+              <MarkdownRenderer content={content} />
+            </>
+          )}
+          </div>
+        </div>
+
+        {/* Table of Contents Sidebar - independent scrollable column */}
+        {showToc && (
+          <div className="hidden lg:block h-full overflow-y-auto border-l border-border bg-muted/30">
+            <div className="p-6 sticky top-0">
+              <TableOfContents items={tocItems} activeId={activeId} visibleIds={visibleIds} onItemClick={handleTocClick} />
+            </div>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// Wrapper component with Suspense boundary for Next.js 15
+export function DocsView() {
+  return (
+    <Suspense fallback={<div className="flex items-center justify-center h-full">Loading documentation...</div>}>
+      <DocsViewContent />
+    </Suspense>
+  );
+}

components/views/interviews-view.tsx

@@ -0,0 +1,11 @@
+'use client';
+
+import { InterviewTemplatesPanel } from '@/components/interview/InterviewTemplatesPanel';
+
+export function InterviewsView() {
+  return (
+    <div className="h-full">
+      <InterviewTemplatesPanel />
+    </div>
+  );
+}

components/views/projects-view.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+import React from 'react';
+import { Project } from '@/lib/vfs/types';
+import { ProjectManager } from '@/components/project-manager';
+
+interface ProjectsViewProps {
+  onProjectSelect: (project: Project) => void;
+  autoCreate?: boolean;
+  workspaceId?: string;
+}
+
+export function ProjectsView({ onProjectSelect, autoCreate, workspaceId }: ProjectsViewProps) {
+  // Use ProjectManager but hide its header and footer since PageLayout provides them
+  return (
+    <ProjectManager
+      onProjectSelect={onProjectSelect}
+      hideHeader={true}
+      hideFooter={true}
+      autoCreate={autoCreate}
+      workspaceId={workspaceId}
+    />
+  );
+}

components/views/settings-view.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import React, { Suspense } from 'react';
+import { useSearchParams } from 'next/navigation';
+import { ProvidersModelsView } from '@/components/providers-models';
+import { SettingsPanel } from '@/components/settings';
+
+interface SettingsViewProps {
+  tab?: 'model' | 'application';
+}
+
+function SettingsViewInner({ tab }: SettingsViewProps) {
+  const searchParams = useSearchParams();
+  // URL param takes precedence, then prop, then default to 'model'
+  const settingsTab = searchParams.get('settings') as 'model' | 'application' | null;
+  const activeTab = settingsTab || tab || 'model';
+
+  return (
+    <div className="h-full flex flex-col">
+      <div className={`flex-1 overflow-auto${activeTab === 'application' ? ' p-6' : ''}`}>
+        {activeTab === 'application' ? <SettingsPanel /> : <ProvidersModelsView />}
+      </div>
+    </div>
+  );
+}
+
+export function SettingsView({ tab }: SettingsViewProps) {
+  return (
+    <Suspense fallback={<div className="h-full flex items-center justify-center"><p className="text-muted-foreground">Loading...</p></div>}>
+      <SettingsViewInner tab={tab} />
+    </Suspense>
+  );
+}

components/views/skills-view.tsx

@@ -0,0 +1,7 @@
+'use client';
+
+import { SkillsManager } from '@/components/skills/SkillsManager';
+
+export function SkillsView() {
+  return <SkillsManager />;
+}

components/views/templates-view.tsx

@@ -0,0 +1,24 @@
+'use client';
+
+import { TemplateManager } from '@/components/template-manager';
+import { useRouter } from 'next/navigation';
+
+interface TemplatesViewProps {
+  onProjectSelect?: (project: { id: string }) => void;
+  onNavigate?: (view: string) => void;
+}
+
+export function TemplatesView({ onProjectSelect, onNavigate }: TemplatesViewProps) {
+  const router = useRouter();
+
+
+  const handleProjectCreated = (projectId: string, _hasBackendFeatures: boolean) => {
+    if (onProjectSelect) {
+      onProjectSelect({ id: projectId });
+    } else {
+      router.push(`/workspace/${projectId}`);
+    }
+  };
+
+  return <TemplateManager onProjectCreated={handleProjectCreated} />;
+}

components/views/users-view.tsx

@@ -0,0 +1,632 @@
+'use client';
+
+import React, { useState, useEffect, useMemo } from 'react';
+import { getLoginUrl } from '@/lib/config/storage';
+import { Users, Plus, Search, MoreHorizontal, UserCheck, UserX, Trash2, Pencil, ChevronRight, ChevronDown, HardDrive, Eye, EyeOff } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Spinner } from '@/components/ui/spinner';
+import { Input } from '@/components/ui/input';
+import { Badge } from '@/components/ui/badge';
+import { Label } from '@/components/ui/label';
+import { Switch } from '@/components/ui/switch';
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogFooter,
+} from '@/components/ui/dialog';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { toast } from 'sonner';
+import { logger } from '@/lib/utils';
+
+interface WorkspaceInfo {
+  id: string;
+  name: string;
+  owner_id: string;
+  max_projects: number;
+  max_deployments: number;
+  max_storage_mb: number;
+  role: string;
+  created_at: string;
+  updated_at: string;
+}
+
+interface UserInfo {
+  id: string;
+  email: string;
+  displayName: string | null;
+  isAdmin: boolean;
+  active: boolean;
+  workspaces: WorkspaceInfo[];
+  projectCount: number;
+  storageMb: number;
+  lastActive: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+
+export function UsersView() {
+  const [users, setUsers] = useState<UserInfo[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [editUser, setEditUser] = useState<UserInfo | null>(null);
+  const [showEditDialog, setShowEditDialog] = useState(false);
+  const [showCreateDialog, setShowCreateDialog] = useState(false);
+  const [saving, setSaving] = useState(false);
+
+  // Edit form state
+  const [editForm, setEditForm] = useState({
+    displayName: '',
+    active: true,
+  });
+
+  // Create form state
+  const [createForm, setCreateForm] = useState({
+    email: '',
+    password: '',
+    displayName: '',
+    workspaceAssignment: 'new' as 'new' | 'existing' | 'none',
+    workspaceId: '',
+  });
+  const [showPassword, setShowPassword] = useState(false);
+
+  const [availableWorkspaces, setAvailableWorkspaces] = useState<Array<{ id: string; name: string }>>([]);
+
+  // Expandable workspace detail state
+  const [expandedUserId, setExpandedUserId] = useState<string | null>(null);
+
+  const isServerMode = process.env.NEXT_PUBLIC_SERVER_MODE === 'true';
+  const isManagedMode = !!process.env.NEXT_PUBLIC_GATEWAY_URL;
+
+  useEffect(() => {
+    loadUsers();
+  }, []);
+
+  useEffect(() => {
+    if (showCreateDialog) {
+      fetch('/api/admin/workspaces')
+        .then(res => res.ok ? res.json() : null)
+        .then(data => {
+          if (data?.workspaces) {
+            setAvailableWorkspaces(data.workspaces.map((w: { id: string; name: string }) => ({ id: w.id, name: w.name })));
+          }
+        })
+        .catch(() => {});
+    }
+  }, [showCreateDialog]);
+
+  const loadUsers = async () => {
+    setLoading(true);
+    try {
+      const res = await fetch('/api/admin/users');
+      if (res.status === 401) {
+        window.location.href = getLoginUrl();
+        return;
+      }
+      if (!res.ok) throw new Error('Failed to load users');
+      const data = await res.json();
+      setUsers(data.users);
+    } catch (err) {
+      logger.error('[UsersView] Failed to load users:', err);
+      toast.error('Failed to load users');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleOpenEdit = (user: UserInfo) => {
+    setEditUser(user);
+    setEditForm({
+      displayName: user.displayName || '',
+      active: user.active,
+    });
+    setShowEditDialog(true);
+  };
+
+  const handleSaveEdit = async () => {
+    if (!editUser) return;
+    setSaving(true);
+    try {
+      const res = await fetch(`/api/admin/users/${editUser.id}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          displayName: editForm.displayName || undefined,
+          active: editForm.active,
+        }),
+      });
+      if (!res.ok) {
+        const error = await res.json();
+        throw new Error(error.error || 'Failed to update user');
+      }
+      toast.success('User updated');
+      setShowEditDialog(false);
+      setEditUser(null);
+      await loadUsers();
+    } catch (err) {
+      logger.error('[UsersView] Failed to update user:', err);
+      toast.error(err instanceof Error ? err.message : 'Failed to update user');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleToggleActive = async (user: UserInfo) => {
+    try {
+      const res = await fetch(`/api/admin/users/${user.id}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ active: !user.active }),
+      });
+      if (!res.ok) {
+        const error = await res.json();
+        throw new Error(error.error || 'Failed to update user');
+      }
+      toast.success(user.active ? 'User deactivated' : 'User reactivated');
+      await loadUsers();
+    } catch (err) {
+      logger.error('[UsersView] Failed to toggle user status:', err);
+      toast.error(err instanceof Error ? err.message : 'Failed to update user');
+    }
+  };
+
+  const handleDelete = async (user: UserInfo) => {
+    if (!confirm(`Deactivate user "${user.email}"? This will soft-delete their account.`)) {
+      return;
+    }
+    try {
+      const res = await fetch(`/api/admin/users/${user.id}`, {
+        method: 'DELETE',
+      });
+      if (!res.ok) {
+        const error = await res.json();
+        throw new Error(error.error || 'Failed to delete user');
+      }
+      toast.success('User deactivated');
+      await loadUsers();
+    } catch (err) {
+      logger.error('[UsersView] Failed to delete user:', err);
+      toast.error(err instanceof Error ? err.message : 'Failed to delete user');
+    }
+  };
+
+  const handleCreate = async () => {
+    if (!createForm.email || !createForm.password) {
+      toast.error('Email and password are required');
+      return;
+    }
+    setSaving(true);
+    try {
+      const res = await fetch('/api/admin/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          email: createForm.email,
+          password: createForm.password,
+          displayName: createForm.displayName || undefined,
+          workspaceAssignment: createForm.workspaceAssignment,
+          workspaceId: createForm.workspaceId || undefined,
+        }),
+      });
+      if (!res.ok) {
+        const error = await res.json();
+        throw new Error(error.error || 'Failed to create user');
+      }
+      toast.success('User created');
+      setShowCreateDialog(false);
+      setCreateForm({ email: '', password: '', displayName: '', workspaceAssignment: 'new', workspaceId: '' });
+      setShowPassword(false);
+      await loadUsers();
+    } catch (err) {
+      logger.error('[UsersView] Failed to create user:', err);
+      toast.error(err instanceof Error ? err.message : 'Failed to create user');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleToggleExpand = (userId: string) => {
+    setExpandedUserId(expandedUserId === userId ? null : userId);
+  };
+
+  const filteredUsers = useMemo(() => {
+    if (!searchQuery) return users;
+    const query = searchQuery.toLowerCase();
+    return users.filter(
+      user =>
+        user.email.toLowerCase().includes(query) ||
+        user.displayName?.toLowerCase().includes(query)
+    );
+  }, [users, searchQuery]);
+
+  const formatDate = (dateStr: string) => {
+    try {
+      return new Date(dateStr).toLocaleDateString(undefined, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      });
+    } catch {
+      return dateStr;
+    }
+  };
+
+  const roleBadgeVariant = (role: string): 'default' | 'secondary' | 'destructive' | 'outline' => {
+    switch (role) {
+      case 'owner': return 'default';
+      case 'editor': return 'secondary';
+      default: return 'outline';
+    }
+  };
+
+  if (!isServerMode) {
+    return (
+      <div className="h-full flex items-center justify-center">
+        <div className="text-center text-muted-foreground">
+          <p>User management is only available in Server Mode</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (loading) {
+    return (
+      <div className="h-full flex items-center justify-center">
+        <div className="text-center">
+          <Spinner size={48} color="#f97316" className="mx-auto" />
+          <p className="mt-4">Loading users...</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <div className="h-full flex flex-col">
+        {/* Toolbar */}
+        <div className="pt-4 px-4 pb-3 sm:pt-6 sm:px-6 sm:pb-3 shrink-0">
+          <div className="mx-auto max-w-7xl flex flex-col sm:flex-row gap-3">
+            {/* Search */}
+            <div className="relative flex-1">
+              <Search className="absolute left-3 top-1/2 transform -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+              <Input
+                placeholder="Search users..."
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                className="pl-9"
+              />
+            </div>
+
+            {/* Controls */}
+            <div className="flex items-center gap-2">
+              {isManagedMode ? (
+                <p className="text-sm text-muted-foreground">
+                  Users are managed externally
+                </p>
+              ) : (
+                <Button onClick={() => setShowCreateDialog(true)} size="sm" className="gap-2">
+                  <Plus className="h-4 w-4" />
+                  <span>New User</span>
+                </Button>
+              )}
+            </div>
+          </div>
+        </div>
+
+        {/* User List */}
+        <div className="flex-1 px-4 pt-3 pb-4 sm:px-6 sm:pt-3 sm:pb-6 overflow-auto">
+          <div className="mx-auto max-w-7xl">
+            {filteredUsers.length === 0 ? (
+              <div className="flex flex-col items-center justify-center py-16 text-center">
+                <Users className="h-16 w-16 text-muted-foreground mb-4" />
+                {users.length === 0 ? (
+                  <>
+                    <h2 className="text-xl font-semibold mb-2">No Users Yet</h2>
+                    <p className="text-muted-foreground mb-4 max-w-md">
+                      Create your first user by clicking the &quot;New User&quot; button above.
+                    </p>
+                  </>
+                ) : (
+                  <>
+                    <h2 className="text-xl font-semibold mb-2">No users found</h2>
+                    <p className="text-muted-foreground mb-4 max-w-md">
+                      Try adjusting your search criteria
+                    </p>
+                  </>
+                )}
+              </div>
+            ) : (
+              <div className="space-y-2">
+                {filteredUsers.map((user) => {
+                  const isExpanded = expandedUserId === user.id;
+                  return (
+                    <div key={user.id} className="rounded-lg border bg-card overflow-hidden">
+                      <div
+                        className="flex items-center gap-4 p-4 hover:bg-accent/50 transition-colors cursor-pointer"
+                        onClick={() => handleToggleExpand(user.id)}
+                      >
+                        {/* Expand chevron */}
+                        <div className="shrink-0 text-muted-foreground">
+                          {isExpanded ? <ChevronDown className="h-4 w-4" /> : <ChevronRight className="h-4 w-4" />}
+                        </div>
+
+                        {/* User Info */}
+                        <div className="flex-1 min-w-0">
+                          <div className="flex items-center gap-2 flex-wrap">
+                            <span className="font-medium truncate">{user.email}</span>
+                            {user.isAdmin && (
+                              <Badge variant="destructive" className="text-xs">admin</Badge>
+                            )}
+                            {!user.active && (
+                              <Badge variant="outline" className="text-xs text-muted-foreground">inactive</Badge>
+                            )}
+                            {user.workspaces.map(ws => (
+                              <Badge key={ws.id} variant={roleBadgeVariant(ws.role)} className="text-xs">
+                                {ws.name} ({ws.role})
+                              </Badge>
+                            ))}
+                          </div>
+                          <div className="text-sm text-muted-foreground mt-1 flex items-center gap-3 flex-wrap">
+                            {user.displayName && (
+                              <span>{user.displayName}</span>
+                            )}
+                            <span>{user.projectCount} projects</span>
+                            <span>
+                              <HardDrive className="inline h-3 w-3 mr-0.5 relative -top-px" />
+                              {user.storageMb} MB
+                            </span>
+                            {user.lastActive ? (
+                              <span>Active {formatDate(user.lastActive)}</span>
+                            ) : (
+                              <span>Created {formatDate(user.createdAt)}</span>
+                            )}
+                          </div>
+                        </div>
+
+                        {/* Actions */}
+                        <DropdownMenu>
+                          <DropdownMenuTrigger asChild>
+                            <Button
+                              variant="ghost"
+                              size="sm"
+                              className="h-8 w-8 p-0"
+                              onClick={(e) => e.stopPropagation()}
+                            >
+                              <MoreHorizontal className="h-4 w-4" />
+                            </Button>
+                          </DropdownMenuTrigger>
+                          <DropdownMenuContent align="end">
+                            <DropdownMenuItem onClick={() => handleOpenEdit(user)}>
+                              <Pencil className="h-4 w-4 mr-2" />
+                              Edit
+                            </DropdownMenuItem>
+                            <DropdownMenuItem onClick={() => handleToggleActive(user)}>
+                              {user.active ? (
+                                <>
+                                  <UserX className="h-4 w-4 mr-2" />
+                                  Deactivate
+                                </>
+                              ) : (
+                                <>
+                                  <UserCheck className="h-4 w-4 mr-2" />
+                                  Reactivate
+                                </>
+                              )}
+                            </DropdownMenuItem>
+                            <DropdownMenuItem
+                              onClick={() => handleDelete(user)}
+                              className="text-destructive focus:text-destructive"
+                            >
+                              <Trash2 className="h-4 w-4 mr-2" />
+                              Delete
+                            </DropdownMenuItem>
+                          </DropdownMenuContent>
+                        </DropdownMenu>
+                      </div>
+
+                      {/* Expanded workspace details */}
+                      {isExpanded && (
+                        <div className="border-t bg-muted/30 px-4 py-3 pl-12">
+                          {user.workspaces.length > 0 ? (
+                            <div className="space-y-2">
+                              <div className="text-xs font-medium text-muted-foreground uppercase tracking-wide mb-2">
+                                Workspaces ({user.workspaces.length})
+                              </div>
+                              {user.workspaces.map((ws) => (
+                                <div
+                                  key={ws.id}
+                                  className="flex items-center gap-3 text-sm p-2 rounded bg-background/60"
+                                >
+                                  <HardDrive className="h-3.5 w-3.5 text-muted-foreground shrink-0" />
+                                  <div className="flex-1 min-w-0">
+                                    <div className="flex items-center gap-2 flex-wrap">
+                                      <span className="font-medium truncate">{ws.name}</span>
+                                    </div>
+                                  </div>
+                                  <div className="flex items-center gap-3 text-xs text-muted-foreground shrink-0">
+                                    <span>{ws.max_projects} projects</span>
+                                    <span>{ws.max_deployments} deployments</span>
+                                    <span>Created {formatDate(ws.created_at)}</span>
+                                  </div>
+                                </div>
+                              ))}
+                            </div>
+                          ) : (
+                            <div className="text-sm text-muted-foreground py-2">
+                              No workspaces assigned
+                            </div>
+                          )}
+                        </div>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Edit User Dialog */}
+      <Dialog open={showEditDialog} onOpenChange={(open) => { setShowEditDialog(open); if (!open) setEditUser(null); }}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Edit User</DialogTitle>
+          </DialogHeader>
+          <div className="space-y-4 py-4">
+            <div className="space-y-2">
+              <Label htmlFor="edit-displayName">Display Name</Label>
+              <Input
+                id="edit-displayName"
+                value={editForm.displayName}
+                onChange={(e) => setEditForm(f => ({ ...f, displayName: e.target.value }))}
+                placeholder="Display name"
+              />
+            </div>
+            <div className="flex items-center gap-2">
+              <Switch
+                id="edit-active"
+                checked={editForm.active}
+                onCheckedChange={(checked) => setEditForm(f => ({ ...f, active: checked }))}
+              />
+              <Label htmlFor="edit-active">Active</Label>
+            </div>
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => { setShowEditDialog(false); setEditUser(null); }}>Cancel</Button>
+            <Button onClick={handleSaveEdit} disabled={saving}>
+              {saving ? 'Saving...' : 'Save Changes'}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {/* Create User Dialog */}
+      <Dialog open={showCreateDialog} onOpenChange={setShowCreateDialog}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Create User</DialogTitle>
+          </DialogHeader>
+          <div className="space-y-4 py-4">
+            <div className="space-y-2">
+              <Label htmlFor="create-email">Email</Label>
+              <Input
+                id="create-email"
+                type="email"
+                value={createForm.email}
+                onChange={(e) => setCreateForm(f => ({ ...f, email: e.target.value }))}
+                placeholder="user@example.com"
+              />
+            </div>
+            <div className="space-y-2">
+              <div className="flex items-center justify-between">
+                <Label htmlFor="create-password">Password</Label>
+                <button
+                  type="button"
+                  className="text-xs text-primary hover:text-primary/80 transition-colors"
+                  onClick={() => {
+                    const chars = 'abcdefghijkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#$%&*';
+                    let pw = '';
+                    const rng = new Uint32Array(16); crypto.getRandomValues(rng);
+                    for (let i = 0; i < 16; i++) pw += chars[rng[i] % chars.length];
+                    setCreateForm(f => ({ ...f, password: pw }));
+                    setShowPassword(true);
+                  }}
+                >
+                  Generate
+                </button>
+              </div>
+              <div className="relative">
+                <Input
+                  id="create-password"
+                  type={showPassword ? 'text' : 'password'}
+                  value={createForm.password}
+                  onChange={(e) => setCreateForm(f => ({ ...f, password: e.target.value }))}
+                  placeholder="Minimum 8 characters"
+                  className="pr-9"
+                />
+                <button
+                  type="button"
+                  onClick={() => setShowPassword(!showPassword)}
+                  className="absolute right-2.5 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground transition-colors"
+                >
+                  {showPassword ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
+                </button>
+              </div>
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="create-displayName">Display Name</Label>
+              <Input
+                id="create-displayName"
+                value={createForm.displayName}
+                onChange={(e) => setCreateForm(f => ({ ...f, displayName: e.target.value }))}
+                placeholder="Display name (optional)"
+              />
+            </div>
+
+            {/* Workspace Assignment */}
+            <div className="space-y-2">
+              <Label>Workspace</Label>
+              <Select
+                value={createForm.workspaceAssignment}
+                onValueChange={(value) => setCreateForm(f => ({
+                  ...f,
+                  workspaceAssignment: value as 'new' | 'existing' | 'none',
+                  workspaceId: '',
+                }))}
+              >
+                <SelectTrigger>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="new">Create new workspace</SelectItem>
+                  <SelectItem value="existing">Assign to existing workspace</SelectItem>
+                  <SelectItem value="none">No workspace</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+
+            {createForm.workspaceAssignment === 'existing' && (
+              <div className="space-y-2">
+                <Label>Select Workspace</Label>
+                <Select
+                  value={createForm.workspaceId}
+                  onValueChange={(value) => setCreateForm(f => ({ ...f, workspaceId: value }))}
+                >
+                  <SelectTrigger>
+                    <SelectValue placeholder="Choose a workspace..." />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {availableWorkspaces.map(ws => (
+                      <SelectItem key={ws.id} value={ws.id}>{ws.name}</SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </div>
+            )}
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setShowCreateDialog(false)}>Cancel</Button>
+            <Button onClick={handleCreate} disabled={saving}>
+              {saving ? 'Creating...' : 'Create User'}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

components/views/workspaces-view.tsx

@@ -0,0 +1,678 @@
+'use client';
+
+import React, { useState, useEffect, useMemo } from 'react';
+import { getLoginUrl } from '@/lib/config/storage';
+import {
+  Building2,
+  Plus,
+  Search,
+  MoreHorizontal,
+  Trash2,
+  Pencil,
+  ChevronRight,
+  ChevronDown,
+  UserPlus,
+  UserMinus,
+} from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import { Spinner } from '@/components/ui/spinner';
+import { Input } from '@/components/ui/input';
+import { Badge } from '@/components/ui/badge';
+import { Label } from '@/components/ui/label';
+import {
+  Dialog,
+  DialogContent,
+  DialogHeader,
+  DialogTitle,
+  DialogFooter,
+} from '@/components/ui/dialog';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { toast } from 'sonner';
+import { logger } from '@/lib/utils';
+
+interface WorkspaceMember {
+  userId: string;
+  email: string;
+  displayName: string | null;
+  role: string;
+  joinedAt: string;
+}
+
+interface WorkspaceInfo {
+  id: string;
+  name: string;
+  ownerId: string;
+  ownerEmail: string | null;
+  maxProjects: number;
+  maxDeployments: number;
+  maxStorageMb: number;
+  memberCount: number;
+  projectCount: number;
+  deploymentCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface WorkspaceDetail extends WorkspaceInfo {
+  members: WorkspaceMember[];
+}
+
+export function WorkspacesView() {
+  const [workspaces, setWorkspaces] = useState<WorkspaceInfo[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [saving, setSaving] = useState(false);
+
+  // Edit dialog
+  const [editWorkspace, setEditWorkspace] = useState<WorkspaceInfo | null>(null);
+  const [showEditDialog, setShowEditDialog] = useState(false);
+  const [editForm, setEditForm] = useState({
+    name: '',
+    maxProjects: 3,
+    maxDeployments: 1,
+    maxStorageMb: 100,
+  });
+
+  // Create dialog
+  const [showCreateDialog, setShowCreateDialog] = useState(false);
+  const [createForm, setCreateForm] = useState({
+    name: '',
+    ownerEmail: '',
+  });
+
+  // Expand / member detail
+  const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [workspaceDetail, setWorkspaceDetail] = useState<WorkspaceDetail | null>(null);
+  const [loadingDetail, setLoadingDetail] = useState(false);
+
+  // Add member dialog
+  const [showAddMemberDialog, setShowAddMemberDialog] = useState(false);
+  const [addMemberForm, setAddMemberForm] = useState({ email: '', role: 'editor' });
+  const [addingMember, setAddingMember] = useState(false);
+
+  const isServerMode = process.env.NEXT_PUBLIC_SERVER_MODE === 'true';
+
+  useEffect(() => {
+    loadWorkspaces();
+  }, []);
+
+  const loadWorkspaces = async () => {
+    setLoading(true);
+    try {
+      const res = await fetch('/api/admin/workspaces');
+      if (res.status === 401) {
+        window.location.href = getLoginUrl();
+        return;
+      }
+      if (!res.ok) throw new Error('Failed to load workspaces');
+      const data = await res.json();
+      setWorkspaces(data.workspaces);
+    } catch (err) {
+      logger.error('[WorkspacesView] Failed to load workspaces:', err);
+      toast.error('Failed to load workspaces');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleOpenEdit = (ws: WorkspaceInfo) => {
+    setEditWorkspace(ws);
+    setEditForm({
+      name: ws.name,
+      maxProjects: ws.maxProjects,
+      maxDeployments: ws.maxDeployments,
+      maxStorageMb: ws.maxStorageMb,
+    });
+    setShowEditDialog(true);
+  };
+
+  const handleSaveEdit = async () => {
+    if (!editWorkspace) return;
+    setSaving(true);
+    try {
+      const res = await fetch(`/api/admin/workspaces/${editWorkspace.id}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: editForm.name || undefined,
+          maxProjects: editForm.maxProjects,
+          maxDeployments: editForm.maxDeployments,
+          maxStorageMb: editForm.maxStorageMb,
+        }),
+      });
+      if (!res.ok) {
+        const error = await res.json();
+        throw new Error(error.error || 'Failed to update workspace');
+      }
+      toast.success('Workspace updated');
+      setShowEditDialog(false);
+      setEditWorkspace(null);
+      await loadWorkspaces();
+      // Refresh detail if expanded
+      if (expandedId === editWorkspace.id) {
+        await loadDetail(editWorkspace.id);
+      }
+    } catch (err) {
+      logger.error('[WorkspacesView] Failed to update workspace:', err);
+      toast.error(err instanceof Error ? err.message : 'Failed to update workspace');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleCreate = async () => {
+    if (!createForm.name || !createForm.ownerEmail) {
+      toast.error('Workspace name and owner email are required');
+      return;
+    }
+    setSaving(true);
+    try {
+      const res = await fetch('/api/admin/workspaces', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          name: createForm.name,
+          ownerEmail: createForm.ownerEmail,
+        }),
+      });
+      if (!res.ok) {
+        const error = await res.json();
+        throw new Error(error.error || 'Failed to create workspace');
+      }
+      toast.success('Workspace created');
+      setShowCreateDialog(false);
+      setCreateForm({ name: '', ownerEmail: '' });
+      await loadWorkspaces();
+    } catch (err) {
+      logger.error('[WorkspacesView] Failed to create workspace:', err);
+      toast.error(err instanceof Error ? err.message : 'Failed to create workspace');
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const handleDelete = async (ws: WorkspaceInfo) => {
+    if (!confirm(`Delete workspace "${ws.name}"? This cannot be undone.`)) return;
+    try {
+      const res = await fetch(`/api/admin/workspaces/${ws.id}`, { method: 'DELETE' });
+      if (!res.ok) {
+        const error = await res.json();
+        throw new Error(error.error || 'Failed to delete workspace');
+      }
+      toast.success('Workspace deleted');
+      if (expandedId === ws.id) {
+        setExpandedId(null);
+        setWorkspaceDetail(null);
+      }
+      await loadWorkspaces();
+    } catch (err) {
+      logger.error('[WorkspacesView] Failed to delete workspace:', err);
+      toast.error(err instanceof Error ? err.message : 'Failed to delete workspace');
+    }
+  };
+
+  const loadDetail = async (wsId: string) => {
+    setLoadingDetail(true);
+    try {
+      const res = await fetch(`/api/admin/workspaces/${wsId}`);
+      if (!res.ok) throw new Error('Failed to load workspace details');
+      const data = await res.json();
+      setWorkspaceDetail(data);
+    } catch (err) {
+      logger.error('[WorkspacesView] Failed to load workspace details:', err);
+      toast.error('Failed to load workspace details');
+      setExpandedId(null);
+    } finally {
+      setLoadingDetail(false);
+    }
+  };
+
+  const handleToggleExpand = async (wsId: string) => {
+    if (expandedId === wsId) {
+      setExpandedId(null);
+      setWorkspaceDetail(null);
+      return;
+    }
+    setExpandedId(wsId);
+    await loadDetail(wsId);
+  };
+
+  const handleAddMember = async () => {
+    if (!expandedId || !addMemberForm.email) {
+      toast.error('Email is required');
+      return;
+    }
+    setAddingMember(true);
+    try {
+      const res = await fetch(`/api/admin/workspaces/${expandedId}/access`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email: addMemberForm.email, role: addMemberForm.role }),
+      });
+      if (!res.ok) {
+        const error = await res.json();
+        throw new Error(error.error || 'Failed to add member');
+      }
+      toast.success('Member added');
+      setShowAddMemberDialog(false);
+      setAddMemberForm({ email: '', role: 'editor' });
+      await loadDetail(expandedId);
+      await loadWorkspaces();
+    } catch (err) {
+      logger.error('[WorkspacesView] Failed to add member:', err);
+      toast.error(err instanceof Error ? err.message : 'Failed to add member');
+    } finally {
+      setAddingMember(false);
+    }
+  };
+
+  const handleRemoveMember = async (wsId: string, userId: string, memberEmail: string) => {
+    if (!confirm(`Remove ${memberEmail} from this workspace?`)) return;
+    try {
+      const res = await fetch(`/api/admin/workspaces/${wsId}/access`, {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ userId }),
+      });
+      if (!res.ok) {
+        const error = await res.json();
+        throw new Error(error.error || 'Failed to remove member');
+      }
+      toast.success('Member removed');
+      await loadDetail(wsId);
+      await loadWorkspaces();
+    } catch (err) {
+      logger.error('[WorkspacesView] Failed to remove member:', err);
+      toast.error(err instanceof Error ? err.message : 'Failed to remove member');
+    }
+  };
+
+  const filteredWorkspaces = useMemo(() => {
+    if (!searchQuery) return workspaces;
+    const query = searchQuery.toLowerCase();
+    return workspaces.filter(
+      ws =>
+        ws.name.toLowerCase().includes(query) ||
+        ws.ownerEmail?.toLowerCase().includes(query)
+    );
+  }, [workspaces, searchQuery]);
+
+  const formatDate = (dateStr: string) => {
+    try {
+      return new Date(dateStr).toLocaleDateString(undefined, {
+        year: 'numeric',
+        month: 'short',
+        day: 'numeric',
+      });
+    } catch {
+      return dateStr;
+    }
+  };
+
+  const roleBadgeVariant = (role: string): 'default' | 'secondary' | 'outline' => {
+    switch (role) {
+      case 'owner': return 'default';
+      case 'editor': return 'secondary';
+      default: return 'outline';
+    }
+  };
+
+  if (!isServerMode) {
+    return (
+      <div className="h-full flex items-center justify-center">
+        <div className="text-center text-muted-foreground">
+          <p>Workspace management is only available in Server Mode</p>
+        </div>
+      </div>
+    );
+  }
+
+  if (loading) {
+    return (
+      <div className="h-full flex items-center justify-center">
+        <div className="text-center">
+          <Spinner size={48} color="#f97316" className="mx-auto" />
+          <p className="mt-4">Loading workspaces...</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <div className="h-full flex flex-col">
+        {/* Toolbar */}
+        <div className="pt-4 px-4 pb-3 sm:pt-6 sm:px-6 sm:pb-3 shrink-0">
+          <div className="mx-auto max-w-7xl flex flex-col sm:flex-row gap-3">
+            <div className="relative flex-1">
+              <Search className="absolute left-3 top-1/2 transform -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+              <Input
+                placeholder="Search workspaces..."
+                value={searchQuery}
+                onChange={(e) => setSearchQuery(e.target.value)}
+                className="pl-9"
+              />
+            </div>
+            <div className="flex items-center gap-2">
+              <Button onClick={() => setShowCreateDialog(true)} size="sm" className="gap-2">
+                <Plus className="h-4 w-4" />
+                <span>New Workspace</span>
+              </Button>
+            </div>
+          </div>
+        </div>
+
+        {/* Workspace List */}
+        <div className="flex-1 px-4 pt-3 pb-4 sm:px-6 sm:pt-3 sm:pb-6 overflow-auto">
+          <div className="mx-auto max-w-7xl">
+            {filteredWorkspaces.length === 0 ? (
+              <div className="flex flex-col items-center justify-center py-16 text-center">
+                <Building2 className="h-16 w-16 text-muted-foreground mb-4" />
+                {workspaces.length === 0 ? (
+                  <>
+                    <h2 className="text-xl font-semibold mb-2">No Workspaces Yet</h2>
+                    <p className="text-muted-foreground mb-4 max-w-md">
+                      Create your first workspace by clicking the &quot;New Workspace&quot; button above.
+                    </p>
+                  </>
+                ) : (
+                  <>
+                    <h2 className="text-xl font-semibold mb-2">No workspaces found</h2>
+                    <p className="text-muted-foreground mb-4 max-w-md">
+                      Try adjusting your search criteria
+                    </p>
+                  </>
+                )}
+              </div>
+            ) : (
+              <div className="space-y-2">
+                {filteredWorkspaces.map((ws) => {
+                  const isExpanded = expandedId === ws.id;
+                  return (
+                    <div key={ws.id} className="rounded-lg border bg-card overflow-hidden">
+                      <div
+                        className="flex items-center gap-4 p-4 hover:bg-accent/50 transition-colors cursor-pointer"
+                        onClick={() => handleToggleExpand(ws.id)}
+                      >
+                        {/* Expand chevron */}
+                        <div className="shrink-0 text-muted-foreground">
+                          {isExpanded ? <ChevronDown className="h-4 w-4" /> : <ChevronRight className="h-4 w-4" />}
+                        </div>
+
+                        {/* Workspace Info */}
+                        <div className="flex-1 min-w-0">
+                          <div className="flex items-center gap-2 flex-wrap">
+                            <span className="font-medium truncate">{ws.name}</span>
+                          </div>
+                          <div className="text-sm text-muted-foreground mt-1 flex items-center gap-3 flex-wrap">
+                            {ws.ownerEmail && (
+                              <span>Owner: {ws.ownerEmail}</span>
+                            )}
+                            <span>{ws.memberCount} {ws.memberCount === 1 ? 'member' : 'members'}</span>
+                            <span>{ws.projectCount} {ws.projectCount === 1 ? 'project' : 'projects'}</span>
+                            <span>Created {formatDate(ws.createdAt)}</span>
+                          </div>
+                        </div>
+
+                        {/* Actions */}
+                        <DropdownMenu>
+                          <DropdownMenuTrigger asChild>
+                            <Button
+                              variant="ghost"
+                              size="sm"
+                              className="h-8 w-8 p-0"
+                              onClick={(e) => e.stopPropagation()}
+                            >
+                              <MoreHorizontal className="h-4 w-4" />
+                            </Button>
+                          </DropdownMenuTrigger>
+                          <DropdownMenuContent align="end">
+                            <DropdownMenuItem onClick={() => handleOpenEdit(ws)}>
+                              <Pencil className="h-4 w-4 mr-2" />
+                              Edit
+                            </DropdownMenuItem>
+                            <DropdownMenuItem
+                              onClick={() => handleDelete(ws)}
+                              className="text-destructive focus:text-destructive"
+                            >
+                              <Trash2 className="h-4 w-4 mr-2" />
+                              Delete
+                            </DropdownMenuItem>
+                          </DropdownMenuContent>
+                        </DropdownMenu>
+                      </div>
+
+                      {/* Expanded members section */}
+                      {isExpanded && (
+                        <div className="border-t bg-muted/30 px-4 py-3 pl-12">
+                          {loadingDetail ? (
+                            <div className="flex items-center gap-2 text-sm text-muted-foreground py-2">
+                              <Spinner size={16} color="#f97316" />
+                              <span>Loading members...</span>
+                            </div>
+                          ) : workspaceDetail ? (
+                            <div className="space-y-3">
+                              {/* Stats row */}
+                              <div className="flex items-center gap-4 text-xs text-muted-foreground">
+                                <span>Max projects: {workspaceDetail.maxProjects}</span>
+                                <span>Max deployments: {workspaceDetail.maxDeployments}</span>
+                                <span>Max storage: {workspaceDetail.maxStorageMb} MB</span>
+                                <span>Deployments: {workspaceDetail.deploymentCount}</span>
+                              </div>
+
+                              {/* Members */}
+                              <div>
+                                <div className="flex items-center justify-between mb-2">
+                                  <div className="text-xs font-medium text-muted-foreground uppercase tracking-wide">
+                                    Members ({workspaceDetail.members.length})
+                                  </div>
+                                  <Button
+                                    size="sm"
+                                    variant="outline"
+                                    className="h-7 text-xs gap-1"
+                                    onClick={(e) => {
+                                      e.stopPropagation();
+                                      setShowAddMemberDialog(true);
+                                    }}
+                                  >
+                                    <UserPlus className="h-3 w-3" />
+                                    Add Member
+                                  </Button>
+                                </div>
+                                {workspaceDetail.members.length > 0 ? (
+                                  <div className="space-y-1">
+                                    {workspaceDetail.members.map((member) => (
+                                      <div
+                                        key={member.userId}
+                                        className="flex items-center gap-3 text-sm p-2 rounded bg-background/60"
+                                        onClick={(e) => e.stopPropagation()}
+                                      >
+                                        <div className="flex-1 min-w-0">
+                                          <div className="flex items-center gap-2 flex-wrap">
+                                            <span className="font-medium truncate">{member.email}</span>
+                                            <Badge variant={roleBadgeVariant(member.role)} className="text-xs">
+                                              {member.role}
+                                            </Badge>
+                                          </div>
+                                          {member.displayName && (
+                                            <div className="text-xs text-muted-foreground">{member.displayName}</div>
+                                          )}
+                                        </div>
+                                        <div className="text-xs text-muted-foreground shrink-0">
+                                          {formatDate(member.joinedAt)}
+                                        </div>
+                                        {member.userId !== workspaceDetail.ownerId && (
+                                          <Button
+                                            variant="ghost"
+                                            size="sm"
+                                            className="h-7 w-7 p-0 text-muted-foreground hover:text-destructive"
+                                            onClick={(e) => {
+                                              e.stopPropagation();
+                                              handleRemoveMember(ws.id, member.userId, member.email);
+                                            }}
+                                            title="Remove member"
+                                          >
+                                            <UserMinus className="h-3.5 w-3.5" />
+                                          </Button>
+                                        )}
+                                      </div>
+                                    ))}
+                                  </div>
+                                ) : (
+                                  <div className="text-sm text-muted-foreground py-1">No members</div>
+                                )}
+                              </div>
+                            </div>
+                          ) : null}
+                        </div>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            )}
+          </div>
+        </div>
+      </div>
+
+      {/* Edit Workspace Dialog */}
+      <Dialog open={showEditDialog} onOpenChange={(open) => { setShowEditDialog(open); if (!open) setEditWorkspace(null); }}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Edit Workspace</DialogTitle>
+          </DialogHeader>
+          <div className="space-y-4 py-4">
+            <div className="space-y-2">
+              <Label htmlFor="edit-name">Name</Label>
+              <Input
+                id="edit-name"
+                value={editForm.name}
+                onChange={(e) => setEditForm(f => ({ ...f, name: e.target.value }))}
+                placeholder="Workspace name"
+              />
+            </div>
+            <div className="grid grid-cols-3 gap-3">
+              <div className="space-y-2">
+                <Label htmlFor="edit-maxProjects">Max Projects</Label>
+                <Input
+                  id="edit-maxProjects"
+                  type="number"
+                  min={0}
+                  value={editForm.maxProjects}
+                  onChange={(e) => setEditForm(f => ({ ...f, maxProjects: Number(e.target.value) }))}
+                />
+              </div>
+              <div className="space-y-2">
+                <Label htmlFor="edit-maxDeployments">Max Deploys</Label>
+                <Input
+                  id="edit-maxDeployments"
+                  type="number"
+                  min={0}
+                  value={editForm.maxDeployments}
+                  onChange={(e) => setEditForm(f => ({ ...f, maxDeployments: Number(e.target.value) }))}
+                />
+              </div>
+              <div className="space-y-2">
+                <Label htmlFor="edit-maxStorage">Storage (MB)</Label>
+                <Input
+                  id="edit-maxStorage"
+                  type="number"
+                  min={0}
+                  value={editForm.maxStorageMb}
+                  onChange={(e) => setEditForm(f => ({ ...f, maxStorageMb: Number(e.target.value) }))}
+                />
+              </div>
+            </div>
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => { setShowEditDialog(false); setEditWorkspace(null); }}>Cancel</Button>
+            <Button onClick={handleSaveEdit} disabled={saving}>
+              {saving ? 'Saving...' : 'Save Changes'}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {/* Create Workspace Dialog */}
+      <Dialog open={showCreateDialog} onOpenChange={setShowCreateDialog}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Create Workspace</DialogTitle>
+          </DialogHeader>
+          <div className="space-y-4 py-4">
+            <div className="space-y-2">
+              <Label htmlFor="create-name">Name</Label>
+              <Input
+                id="create-name"
+                value={createForm.name}
+                onChange={(e) => setCreateForm(f => ({ ...f, name: e.target.value }))}
+                placeholder="Workspace name"
+              />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="create-ownerEmail">Owner Email</Label>
+              <Input
+                id="create-ownerEmail"
+                type="email"
+                value={createForm.ownerEmail}
+                onChange={(e) => setCreateForm(f => ({ ...f, ownerEmail: e.target.value }))}
+                placeholder="owner@example.com"
+              />
+            </div>
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setShowCreateDialog(false)}>Cancel</Button>
+            <Button onClick={handleCreate} disabled={saving}>
+              {saving ? 'Creating...' : 'Create Workspace'}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {/* Add Member Dialog */}
+      <Dialog open={showAddMemberDialog} onOpenChange={setShowAddMemberDialog}>
+        <DialogContent className="sm:max-w-md">
+          <DialogHeader>
+            <DialogTitle>Add Member</DialogTitle>
+          </DialogHeader>
+          <div className="space-y-4 py-4">
+            <div className="space-y-2">
+              <Label htmlFor="add-member-email">User Email</Label>
+              <Input
+                id="add-member-email"
+                type="email"
+                value={addMemberForm.email}
+                onChange={(e) => setAddMemberForm(f => ({ ...f, email: e.target.value }))}
+                placeholder="user@example.com"
+              />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="add-member-role">Role</Label>
+              <select
+                id="add-member-role"
+                className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm"
+                value={addMemberForm.role}
+                onChange={(e) => setAddMemberForm(f => ({ ...f, role: e.target.value }))}
+              >
+                <option value="viewer">viewer</option>
+                <option value="editor">editor</option>
+                <option value="owner">owner</option>
+              </select>
+            </div>
+          </div>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setShowAddMemberDialog(false)}>Cancel</Button>
+            <Button onClick={handleAddMember} disabled={addingMember}>
+              {addingMember ? 'Adding...' : 'Add Member'}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}

components/workspace-switcher/index.tsx

@@ -0,0 +1,130 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import { useRouter, usePathname } from 'next/navigation';
+import { ChevronDown, Building2, Settings } from 'lucide-react';
+import { Button } from '@/components/ui/button';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import { Badge } from '@/components/ui/badge';
+
+interface WorkspaceInfo {
+  id: string;
+  name: string;
+  owner_id: string;
+  role: string;
+}
+
+interface WorkspaceSwitcherProps {
+  workspaceId?: string;
+}
+
+export function WorkspaceSwitcher({ workspaceId }: WorkspaceSwitcherProps) {
+  // Read cached name from localStorage after mount (avoids hydration mismatch)
+  const [cachedName, setCachedName] = useState<string | null>(null);
+  useEffect(() => {
+    try {
+      const name = localStorage.getItem('osw-workspace-name');
+      if (name) setCachedName(name);
+    } catch {}
+  }, []);
+  const [workspaces, setWorkspaces] = useState<WorkspaceInfo[]>([]);
+  const [isAdmin, setIsAdmin] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const router = useRouter();
+  const pathname = usePathname();
+
+  useEffect(() => {
+    Promise.all([
+      fetch('/api/workspaces').then(res => res.ok ? res.json() : null),
+      fetch('/api/auth/me').then(res => res.ok ? res.json() : null),
+    ])
+      .then(([wsData, authData]) => {
+        if (wsData?.workspaces) {
+          setWorkspaces(wsData.workspaces);
+          // Update cached name from fresh data
+          const current = wsData.workspaces.find((w: WorkspaceInfo) => w.id === workspaceId);
+          if (current) {
+            try { localStorage.setItem('osw-workspace-name', current.name); } catch {}
+          }
+        }
+        if (authData?.user?.isAdmin) setIsAdmin(true);
+      })
+      .catch(() => {})
+      .finally(() => setLoading(false));
+  }, [workspaceId]);
+
+  const currentWorkspace = workspaces.find(w => w.id === workspaceId);
+
+  const handleSwitch = (newWorkspaceId: string) => {
+    const viewMatch = pathname?.match(/\/w\/[^/]+\/(.+)/);
+    const currentView = viewMatch?.[1] || 'projects';
+    document.cookie = `osw_workspace=${newWorkspaceId};path=/;max-age=${60 * 60 * 24 * 365}`;
+    const ws = workspaces.find(w => w.id === newWorkspaceId);
+    if (ws) {
+      try { localStorage.setItem('osw-workspace-name', ws.name); } catch {}
+    }
+    router.push(`/w/${newWorkspaceId}/${currentView}`);
+  };
+
+  // While loading, show cached name if available (prevents flash)
+  if (loading) {
+    if (!cachedName) return null;
+    return (
+      <div className="border-b border-border/50">
+        <Button variant="ghost" className="w-full justify-start gap-2 px-3 py-2.5 h-auto rounded-none" disabled>
+          <Building2 className="h-4 w-4 text-foreground shrink-0" />
+          <span className="truncate font-medium text-sm text-foreground">{cachedName}</span>
+          <ChevronDown className="h-3 w-3 ml-auto text-muted-foreground shrink-0" />
+        </Button>
+      </div>
+    );
+  }
+
+  if (workspaces.length === 0) return null;
+
+  // Always show as dropdown — single workspace gets manage option, multiple gets switcher
+  return (
+    <div className="border-b border-border/50">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button variant="ghost" className="w-full justify-start gap-2 px-3 py-2.5 h-auto rounded-none hover:bg-accent/50">
+            <Building2 className="h-4 w-4 text-foreground shrink-0" />
+            <span className="truncate font-medium text-sm text-foreground">
+              {currentWorkspace?.name || cachedName || workspaces[0]?.name || 'Workspace'}
+            </span>
+            <ChevronDown className="h-3 w-3 ml-auto text-muted-foreground shrink-0" />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="start" className="w-64">
+          {workspaces.map(ws => (
+            <DropdownMenuItem
+              key={ws.id}
+              onClick={() => handleSwitch(ws.id)}
+              className={ws.id === workspaceId ? 'bg-accent' : ''}
+            >
+              <div className="flex items-center gap-2 w-full min-w-0">
+                <span className="truncate flex-1">{ws.name}</span>
+                <Badge variant="outline" className="text-[10px] shrink-0">{ws.role}</Badge>
+              </div>
+            </DropdownMenuItem>
+          ))}
+          {isAdmin && (
+            <>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem onClick={() => router.push('/admin/workspaces')}>
+                <Settings className="h-3.5 w-3.5 mr-2" />
+                Manage Workspaces
+              </DropdownMenuItem>
+            </>
+          )}
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  );
+}

components/workspace/deployment-selector.tsx

@@ -0,0 +1,135 @@
+'use client';
+
+import React, { useEffect, useState } from 'react';
+import { Deployment } from '@/lib/vfs/types';
+import { Server, Loader2 } from 'lucide-react';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { cn } from '@/lib/utils';
+
+interface DeploymentSelectorProps {
+  projectId: string;
+  selectedDeploymentId: string | null;
+  onDeploymentChange: (deploymentId: string | null, deploymentName: string | null) => void;
+  className?: string;
+  workspaceId?: string;
+}
+
+export function DeploymentSelector({
+  projectId,
+  selectedDeploymentId,
+  onDeploymentChange,
+  className,
+  workspaceId,
+}: DeploymentSelectorProps) {
+  const apiBase = workspaceId ? `/api/w/${workspaceId}` : '/api';
+  const [deployments, setDeployments] = useState<Deployment[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  // Fetch deployments for this project
+  useEffect(() => {
+    const fetchDeployments = async () => {
+      // Only fetch in server mode
+      if (process.env.NEXT_PUBLIC_SERVER_MODE !== 'true') {
+        setLoading(false);
+        return;
+      }
+
+      try {
+        setLoading(true);
+        setError(null);
+
+        const response = await fetch(`${apiBase}/projects/${projectId}/deployments`);
+        if (!response.ok) {
+          throw new Error('Failed to fetch deployments');
+        }
+
+        const data = await response.json();
+        setDeployments(data.deployments || []);
+
+        // Auto-select first deployment if only one exists and nothing is selected
+        if (data.deployments?.length === 1 && !selectedDeploymentId) {
+          const deployment = data.deployments[0];
+          if (deployment.databaseEnabled) {
+            onDeploymentChange(deployment.id, deployment.name);
+          }
+        }
+      } catch {
+        // Expected in browser mode or when project hasn't been synced to server yet
+        // Don't show error — deployments are optional
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    fetchDeployments();
+  }, [projectId]); // Only refetch when project changes
+
+  // Don't render in browser mode
+  if (process.env.NEXT_PUBLIC_SERVER_MODE !== 'true') {
+    return null;
+  }
+
+  // Don't render if no deployments with database enabled
+  const databaseEnabledDeployments = deployments.filter(s => s.databaseEnabled);
+  if (!loading && databaseEnabledDeployments.length === 0) {
+    return null;
+  }
+
+  if (loading) {
+    return (
+      <div className={cn('flex items-center gap-2 text-sm text-muted-foreground', className)}>
+        <Loader2 className="h-4 w-4 animate-spin" />
+        <span>Loading deployments...</span>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className={cn('flex items-center gap-2 text-sm text-destructive', className)}>
+        <Server className="h-4 w-4" />
+        <span>{error}</span>
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn('flex items-center gap-2', className)}>
+      <Select
+        value={selectedDeploymentId || 'none'}
+        onValueChange={(value) => {
+          if (value === 'none') {
+            onDeploymentChange(null, null);
+          } else {
+            const deployment = deployments.find(s => s.id === value);
+            onDeploymentChange(value, deployment?.name || null);
+          }
+        }}
+      >
+        <SelectTrigger size="sm" className="w-[180px] h-8">
+          <SelectValue placeholder="No deployment" />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="none">
+            <span className="text-muted-foreground">No deployment</span>
+          </SelectItem>
+          {databaseEnabledDeployments.map((deployment) => (
+            <SelectItem key={deployment.id} value={deployment.id}>
+              <div className="flex items-center gap-2">
+                <Server className="h-3.5 w-3.5" />
+                <span>{deployment.name}</span>
+              </div>
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </div>
+  );
+}

components/workspace/index.tsx

@@ -0,0 +1,2257 @@
+'use client';
+
+import React, { useCallback, useEffect, useRef, useMemo } from 'react';
+import { Project, VirtualFile } from '@/lib/vfs/types';
+import { vfs } from '@/lib/vfs';
+import { logger } from '@/lib/utils';
+import { FileExplorer } from '@/components/file-explorer';
+import { MultiTabEditor, openFileInEditor } from '@/components/editor/multi-tab-editor';
+import { MultipagePreview, MultipagePreviewHandle } from '@/components/preview/multipage-preview';
+import { Button } from '@/components/ui/button';
+import { ArrowLeft, MessageSquare, FolderTree, Code2, Eye, Settings, Save, Bug, RotateCcw, History, Settings2, Terminal as TerminalIcon, Sparkles, ChevronDown, ChevronUp, EllipsisVertical } from 'lucide-react';
+import { AppHeader, HeaderAction } from '@/components/ui/app-header';
+import { PendingImage, PendingAudio, PendingFile } from '@/lib/llm/multi-agent-orchestrator';
+import { configManager, migrateBackendKey } from '@/lib/config/storage';
+import { useWorkspaceStore } from '@/lib/stores/workspace';
+import type { InterviewTemplate, InterviewHandoff } from '@/lib/interview/types';
+import { track } from '@/lib/telemetry';
+import { bucketInterviewTemplateId } from '@/lib/telemetry/tool-analytics';
+import { PANEL_MAP } from '@/lib/stores/slices/layout';
+import { useCostSettings } from '@/lib/hooks/use-cost-settings';
+import { getModelInputModalities } from '@/lib/llm/providers/registry';
+import { isProjectProviderReady } from '@/lib/llm/models/project-assignment';
+import { resolveActiveAssignment } from '@/lib/llm/models/template-store';
+import { toast } from 'sonner';
+import { debugEventsState } from '@/lib/llm/debug-events-state';
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from '@/components/ui/resizable';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/components/ui/tooltip';
+import { checkpointManager } from '@/lib/vfs/checkpoint';
+import { saveManager } from '@/lib/vfs/save-manager';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@/components/ui/popover';
+import { SettingsPanel } from '@/components/settings';
+import { GuidedTourOverlay } from '@/components/guided-tour/overlay';
+import { useGuidedTour } from '@/components/guided-tour/context';
+import { GuidedTourTranscriptEvent } from '@/components/guided-tour/types';
+import { FocusContextPayload } from '@/lib/preview/types';
+import type { PlacedBlock } from '@/lib/semantic-blocks/types';
+import type { PlacementResult } from '@/lib/preview/types';
+import { getBlockById } from '@/lib/semantic-blocks/registry';
+import { DebugPanel } from '@/components/debug-panel';
+import { ChatPanel } from '@/components/chat-panel';
+import { DeploymentSelector } from '@/components/workspace/deployment-selector';
+import { CheckpointPanel } from '@/components/checkpoint-panel';
+import { ProjectSettingsModal } from '@/components/project-backend';
+import { SkillsPanel } from '@/components/workspace/skills-panel';
+import { PanelDragProvider } from '@/components/ui/panel';
+import { ConsolePanel } from '@/components/console';
+import { drainRuntimeErrors, peekRuntimeErrors, formatRuntimeErrors } from '@/lib/preview/runtime-errors';
+
+interface WorkspaceProps {
+  project: Project;
+  onBack: () => void;
+  workspaceId?: string;
+}
+
+type FocusTarget = FocusContextPayload & { timestamp: number };
+
+export function Workspace({ project, onBack, workspaceId }: WorkspaceProps) {
+  const refreshTrigger = useWorkspaceStore(s => s.refreshTrigger);
+  const generating = useWorkspaceStore(s => s.generating);
+  const debugEvents = useWorkspaceStore(s => s.debugEvents);
+  const currentModel = useWorkspaceStore(s => s.currentModel);
+  const modelConfigVersion = useWorkspaceStore(s => s.modelConfigVersion);
+  const projectCost = useWorkspaceStore(s => s.projectCost);
+  const addDebugEvent = useWorkspaceStore(s => s.addDebugEvent);
+  const isDirty = useWorkspaceStore(s => s.isDirty);
+  const saveInProgress = useWorkspaceStore(s => s.saveInProgress);
+  const entryPoint = useWorkspaceStore(s => s.entryPoint);
+  const projectRuntime = useWorkspaceStore(s => s.projectRuntime);
+  const focusContext = useWorkspaceStore(s => s.focusContext);
+  const mode = useWorkspaceStore(s => s.mode);
+  const activeInterview = useWorkspaceStore(s => s.activeInterview);
+  const runtimeErrors = useWorkspaceStore(s => s.runtimeErrors);
+  const initialCheckpointId = useWorkspaceStore(s => s.initialCheckpointId);
+  const checkpointRefreshKey = useWorkspaceStore(s => s.checkpointRefreshKey);
+  const backendEnabled = useWorkspaceStore(s => s.backendEnabled);
+  const selectedDeploymentId = useWorkspaceStore(s => s.selectedDeploymentId);
+  const activeMobilePanel = useWorkspaceStore(s => s.activeMobilePanel);
+  const mobileOverflowOpen = useWorkspaceStore(s => s.mobileOverflowOpen);
+  const placedBlocks = useWorkspaceStore(s => s.placedBlocks);
+  const paletteOpen = useWorkspaceStore(s => s.paletteOpen);
+  const lastFocusSignatureRef = useRef<{ signature: string; timestamp: number } | null>(null);
+  const previewRef = useRef<MultipagePreviewHandle>(null);
+  const generatingRef = useRef(false);
+  const handleGenerateRef = useRef<((promptText?: string, images?: PendingImage[], audio?: PendingAudio[], files?: PendingFile[]) => Promise<void>) | null>(null);
+  const storeSetMode = useWorkspaceStore(s => s.setMode);
+  const storeSetActiveInterview = useWorkspaceStore(s => s.setActiveInterview);
+  const storeFocusContext = useWorkspaceStore(s => s.setFocusContext);
+  const { state: tourState, setWorkspaceHandler } = useGuidedTour();
+  const tourStep = tourState.currentStep?.id;
+  const tourRunning = tourState.status === 'running';
+  const isTourLockingInput = tourRunning && tourStep !== 'wrap-up';
+
+  // Keep generatingRef in sync for runtime error listener
+  useEffect(() => { generatingRef.current = generating; }, [generating]);
+
+  // Guard against accidental navigation away with unsaved changes
+  // During generation, let the user leave freely — the generation shelf handles status
+  const guardedBack = useCallback(() => {
+    if (!generating && isDirty) {
+      if (!window.confirm('You have unsaved changes. Leave anyway?')) return;
+    }
+    onBack();
+  }, [generating, isDirty, onBack]);
+
+  // Reattach to any server-side tasks that were running before page reload
+  useEffect(() => {
+    useWorkspaceStore.getState().reattachServerTasks();
+  }, []);
+
+  // Browser beforeunload — warn when dirty or generating
+  useEffect(() => {
+    const handler = (e: BeforeUnloadEvent) => {
+      if (useWorkspaceStore.getState().isAnyGenerating() || isDirty) {
+        e.preventDefault();
+      }
+    };
+    window.addEventListener('beforeunload', handler);
+    return () => window.removeEventListener('beforeunload', handler);
+  }, [isDirty]);
+
+  // Subscribe to runtime errors that arrive after generation completes
+  useEffect(() => {
+    const handler = () => {
+      if (!generatingRef.current) {
+        useWorkspaceStore.getState().setRuntimeErrors(peekRuntimeErrors());
+      }
+    };
+    window.addEventListener('runtimeErrorsChanged', handler);
+    return () => window.removeEventListener('runtimeErrorsChanged', handler);
+  }, []);
+
+  // The reactive model-config signal bump (apiKeyUpdated + modelConfigChanged -> bumpModelConfig)
+  // lives in the useModelConfigSignal hook, mounted at the always-present mode roots (StudioInner
+  // and PageWrapperInner). Mounting it there (not here) makes modelConfigVersion bump globally so
+  // ChatPanels rendered outside the Workspace subtree (describe-mode, project-manager) also react.
+
+  // Listen for runtime changes from the CLI (e.g., LLM runs `runtime handlebars`)
+  useEffect(() => {
+    const handler = (e: Event) => {
+      const runtime = (e as CustomEvent).detail?.runtime;
+      if (runtime) useWorkspaceStore.getState().updateProjectSettings({ runtime });
+    };
+    window.addEventListener('runtimeChanged', handler);
+    return () => window.removeEventListener('runtimeChanged', handler);
+  }, []);
+
+  // The GLOBAL model auto-assign on provider connect (apiKeyUpdated -> activateProviderAsGlobalDefault)
+  // lives in the useProviderAutoAssign hook, mounted at the always-present mode roots (StudioInner and
+  // PageWrapperInner). It cannot live here: the Connections UI is reachable outside a workspace
+  // (dashboard -> Settings -> Connections), where Workspace is not mounted.
+
+  // Get cost settings for conditional display
+  const { shouldShowCosts } = useCostSettings();
+
+  // Input modalities of the active agent model (drives image/voice affordances).
+  // Resolve from the globally-resolved active assignment, falling back to the
+  // global selectedProvider/currentModel.
+  const inputModalities = useMemo(() => {
+    const agent = resolveActiveAssignment().agent;
+    const currentProvider = agent?.provider ?? configManager.getSelectedProvider();
+    const modelId = agent?.model || currentModel || configManager.getDefaultModel();
+
+    // Check cached discovered models first (has accurate modality data from API)
+    const cached = configManager.getCachedModels(currentProvider);
+    if (cached) {
+      const model = (cached.models as import('@/lib/llm/providers/types').ProviderModel[])
+        .find(m => m.id === modelId);
+      if (model?.inputModalities) return model.inputModalities;
+      if (model?.supportsVision !== undefined) {
+        return model.supportsVision ? ['text' as const, 'image' as const] : ['text' as const];
+      }
+    }
+
+    return getModelInputModalities(currentProvider, modelId);
+  }, [modelConfigVersion, currentModel]);
+
+  const supportsVision = inputModalities.includes('image');
+
+  // Readiness keys off the globally-resolved active agent provider
+  // (see isProjectProviderReady), recomputed on modelConfigVersion bumps.
+  const providerReady = useMemo(
+    () => isProjectProviderReady(),
+    [modelConfigVersion],
+  );
+  
+  // Console panel — visible by default for terminal-mode runtimes (Python, Lua), togglable for all
+
+  const showChat = useWorkspaceStore(s => s.showChat);
+  const showFiles = useWorkspaceStore(s => s.showFiles);
+  const showEditor = useWorkspaceStore(s => s.showEditor);
+  const showPreview = useWorkspaceStore(s => s.showPreview);
+  const showCheckpoints = useWorkspaceStore(s => s.showCheckpoints);
+  const showDebugPanel = useWorkspaceStore(s => s.showDebugPanel);
+  const showProjectSettingsModal = useWorkspaceStore(s => s.showProjectSettingsModal);
+  const showSkillsPanel = useWorkspaceStore(s => s.showSkillsPanel);
+  const showConsole = useWorkspaceStore(s => s.showConsole);
+  const fullscreenPreview = useWorkspaceStore(s => s.fullscreenPreview);
+  const panelReplacePreview = useWorkspaceStore(s => s.panelReplacePreview);
+  const panelInsertPreview = useWorkspaceStore(s => s.panelInsertPreview);
+  const hasUnreadConsole = useWorkspaceStore(s => s.hasUnreadConsole);
+  // Ref to imperatively reset panel sizes after reorder
+  const panelGroupRef = useRef<import('react-resizable-panels').ImperativePanelGroupHandle | null>(null);
+
+  const panelOrder = useWorkspaceStore(s => s.panelOrder);
+  const draggingPanel = useWorkspaceStore(s => s.draggingPanel);
+  const dropTarget = useWorkspaceStore(s => s.dropTarget);
+
+  const handlePanelDragStart = useCallback((panelKey: string) => {
+    // Capture the dragged panel's center X for "stay put" distance comparison
+    const container = panelContainerRef.current;
+    if (container) {
+      const panelEl = container.querySelector(`[data-panel-id="${panelKey}"]`);
+      if (panelEl) {
+        const rect = panelEl.getBoundingClientRect();
+        draggedPanelCenter.current = rect.left + rect.width / 2;
+      }
+    }
+    document.body.style.cursor = 'grabbing';
+    useWorkspaceStore.getState().startDrag(panelKey);
+  }, []);
+
+  const handlePanelDragEnd = useCallback(() => {
+    if (draggingPanel && dropTarget !== null) {
+      // Capture current sizes keyed by panel identity before reordering
+      const visibleBefore = panelOrder.filter(k => {
+        if (k === 'chat') return showChat;
+        if (k === 'files') return showFiles;
+        if (k === 'editor') return showEditor;
+        if (k === 'console') return showConsole;
+        if (k === 'preview') return showPreview;
+        if (k === 'checkpoints') return showCheckpoints;
+        if (k === 'debug') return showDebugPanel;
+        if (k === 'skills') return showSkillsPanel;
+        return false;
+      });
+      const currentLayout = panelGroupRef.current?.getLayout() || [];
+      const sizeByKey: Record<string, number> = {};
+      visibleBefore.forEach((key, i) => {
+        if (i < currentLayout.length) sizeByKey[key] = currentLayout[i];
+      });
+
+      {
+        const prevOrder = panelOrder;
+        const newOrder = prevOrder.filter(k => k !== draggingPanel);
+        const targetKey = visibleBefore[dropTarget];
+        if (targetKey) {
+          const insertIdx = newOrder.indexOf(targetKey);
+          newOrder.splice(insertIdx, 0, draggingPanel);
+        } else {
+          newOrder.push(draggingPanel);
+        }
+        useWorkspaceStore.getState().setPanelOrder(newOrder);
+      }
+
+      // Restore sizes in the new order after React re-renders
+      requestAnimationFrame(() => {
+        if (panelGroupRef.current && visibleBefore.length > 0) {
+          // Compute new visible order
+          const newVisible = [...visibleBefore];
+          const dragIdx = newVisible.indexOf(draggingPanel);
+          if (dragIdx >= 0) newVisible.splice(dragIdx, 1);
+          const targetKey = visibleBefore[dropTarget];
+          const insertIdx = targetKey ? newVisible.indexOf(targetKey) : newVisible.length;
+          newVisible.splice(insertIdx >= 0 ? insertIdx : newVisible.length, 0, draggingPanel);
+
+          const sizes = newVisible.map(k => sizeByKey[k] || Math.floor(100 / newVisible.length));
+          // Normalize to exactly 100
+          const total = sizes.reduce((a, b) => a + b, 0);
+          if (total !== 100 && sizes.length > 0) {
+            sizes[sizes.length - 1] += 100 - total;
+          }
+          panelGroupRef.current.setLayout(sizes);
+        }
+      });
+    }
+    useWorkspaceStore.getState().endDrag();
+    draggedPanelCenter.current = null;
+    document.body.style.cursor = '';
+  }, [draggingPanel, dropTarget, panelOrder, showChat, showFiles, showEditor, showConsole, showPreview, showCheckpoints, showDebugPanel, showSkillsPanel]);
+
+  // Document-level mouseup listener — ends drag whether inside or outside the container.
+  // If mouseUp is inside the container, the container's own onMouseUp handles it (with drop logic).
+  // If mouseUp is outside, this fires and cancels the drag.
+  useEffect(() => {
+    if (!draggingPanel) return;
+    const handleDocumentMouseUp = () => {
+      // Only cancel if still dragging — the container's onMouseUp may have already handled it
+      if (useWorkspaceStore.getState().draggingPanel) {
+        useWorkspaceStore.getState().endDrag();
+        draggedPanelCenter.current = null;
+        document.body.style.cursor = '';
+      }
+    };
+    document.addEventListener('mouseup', handleDocumentMouseUp);
+    return () => document.removeEventListener('mouseup', handleDocumentMouseUp);
+  }, [draggingPanel]);
+
+  // During drag: track mouse X and find closest drop zone
+  const panelContainerRef = useRef<HTMLDivElement>(null);
+  const dropZonePositions = useRef<Map<number, number>>(new Map()); // position index → X center
+  const draggedPanelCenter = useRef<number | null>(null); // X center of the panel being dragged
+
+  const registerDropZone = useCallback((position: number, el: HTMLDivElement | null) => {
+    if (el) {
+      const rect = el.getBoundingClientRect();
+      dropZonePositions.current.set(position, rect.left + rect.width / 2);
+    } else {
+      dropZonePositions.current.delete(position);
+    }
+  }, []);
+
+  const handleDragMouseMove = useCallback((e: React.MouseEvent) => {
+    if (!draggingPanel) return;
+    const positions = dropZonePositions.current;
+    if (positions.size === 0) return;
+
+    // Check distance to each drop zone
+    let closest: number | null = null;
+    let closestDist = Infinity;
+    for (const [pos, x] of positions) {
+      const dist = Math.abs(e.clientX - x);
+      if (dist < closestDist) {
+        closestDist = dist;
+        closest = pos;
+      }
+    }
+
+    // If the mouse is closer to the dragged panel's own center, stay put (no move)
+    if (draggedPanelCenter.current !== null) {
+      const distToSelf = Math.abs(e.clientX - draggedPanelCenter.current);
+      if (distToSelf <= closestDist) {
+        useWorkspaceStore.getState().setDropTarget(null);
+        return;
+      }
+    }
+
+    useWorkspaceStore.getState().setDropTarget(closest);
+  }, [draggingPanel]);
+
+  const togglePanel = useWorkspaceStore(s => s.togglePanel);
+
+  const handleSidebarHover = useCallback((key: string | null) => {
+    const store = useWorkspaceStore.getState();
+    if (!key) { store.setPanelReplacePreview(null); store.setPanelInsertPreview(null); return; }
+    const panelStateKey = PANEL_MAP[key];
+    if (!panelStateKey || store[panelStateKey]) { store.setPanelReplacePreview(null); store.setPanelInsertPreview(null); return; }
+    const allPanels = store.panelOrder
+      .filter(k => PANEL_MAP[k] !== undefined)
+      .map(k => ({ key: k, open: !!store[PANEL_MAP[k]] }));
+    const visibleCount = allPanels.filter(p => p.open).length;
+    const MAX_VISIBLE_PANELS = 3;
+    if (visibleCount < MAX_VISIBLE_PANELS) {
+      store.setPanelInsertPreview(visibleCount);
+      store.setPanelReplacePreview(null);
+      return;
+    }
+    store.setPanelInsertPreview(null);
+    for (let i = allPanels.length - 1; i >= 0; i--) {
+      if (allPanels[i].open && allPanels[i].key !== key) {
+        store.setPanelReplacePreview(allPanels[i].key);
+        return;
+      }
+    }
+    store.setPanelReplacePreview(null);
+  }, []);
+
+  const consoleBufferRef = useRef<{ level: string; text: string }[]>([]);
+  const showConsoleRef = useRef(showConsole);
+
+  // Keep showConsoleRef in sync for buffering logic (tracks both desktop and mobile)
+  useEffect(() => {
+    showConsoleRef.current = showConsole || activeMobilePanel === 'console';
+  }, [showConsole, activeMobilePanel]);
+
+  // Buffer previewConsole events when console is hidden
+  useEffect(() => {
+    const handler = (e: Event) => {
+      if (!showConsoleRef.current) {
+        const { level, args } = (e as CustomEvent<{ level: string; args: string[] }>).detail;
+        consoleBufferRef.current.push({ level, text: args.join(' ') });
+        useWorkspaceStore.getState().setHasUnreadConsole(true);
+      }
+    };
+    window.addEventListener('previewConsole', handler);
+    return () => window.removeEventListener('previewConsole', handler);
+  }, []);
+
+  // Clear unread flag when console opens (desktop or mobile)
+  useEffect(() => {
+    if (showConsole || activeMobilePanel === 'console') {
+      useWorkspaceStore.getState().setHasUnreadConsole(false);
+    }
+  }, [showConsole, activeMobilePanel]);
+
+  const clearDebugEvents = useCallback(async () => {
+    await useWorkspaceStore.getState().clearChat(project.id);
+    // Clear auto-checkpoints when conversation is cleared (keep manual saves)
+    await checkpointManager.clearAutoCheckpoints(project.id);
+    // Clearing the chat also ends any active interview (returns to the picker).
+    // Note: this counts as abandoned even if the interview had already completed
+    // and the user is just clearing up afterwards; acceptable minor over-count.
+    const endingInterview = useWorkspaceStore.getState().activeInterview;
+    if (endingInterview) {
+      track('interview_abandoned', { template: bucketInterviewTemplateId(endingInterview.templateId) });
+    }
+    useWorkspaceStore.getState().setActiveInterview(null);
+  }, [project.id]);
+  
+  const visiblePanelCount = [showChat, showFiles, showEditor, showConsole, showPreview, showCheckpoints, showDebugPanel, showSkillsPanel].filter(Boolean).length;
+  const baseSize = visiblePanelCount > 0 ? Math.floor(100 / visiblePanelCount) : 100;
+
+  const getModelDisplayName = (modelId: string) => {
+    if (!modelId) return 'Select Model';
+    const parts = modelId.split('/');
+    const modelName = parts[parts.length - 1];
+    return modelName
+      .split('-')
+      .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+      .join(' ');
+  };
+
+  const truncateHtmlSnippet = useCallback((html: string, maxLength: number = 1200) => {
+    if (!html) {
+      return '';
+    }
+    if (html.length <= maxLength) {
+      return html;
+    }
+    const headLength = Math.max(0, Math.floor(maxLength * 0.6));
+    const tailLength = Math.max(0, Math.floor(maxLength * 0.3));
+    const head = html.slice(0, headLength);
+    const tail = tailLength > 0 ? html.slice(-tailLength) : '';
+    return `${head}\n  (...truncated...)\n${tail}`;
+  }, []);
+
+  // Truncate an HTML snippet so the given marker comment stays visible with
+  // surrounding context on both sides. Used for semantic block drops where the
+  // marker's position is the whole point of the snippet — head/tail truncation
+  // would drop the marker whenever it falls in the middle of a large parent.
+  const truncateHtmlAroundMarker = useCallback((html: string, marker: string, maxLength: number = 1200) => {
+    if (!html) return '';
+    if (html.length <= maxLength) return html;
+    const markerIdx = html.indexOf(marker);
+    if (markerIdx === -1) {
+      // Fall back to head/tail when the marker isn't present
+      const headLength = Math.max(0, Math.floor(maxLength * 0.6));
+      const tailLength = Math.max(0, Math.floor(maxLength * 0.3));
+      const head = html.slice(0, headLength);
+      const tail = tailLength > 0 ? html.slice(-tailLength) : '';
+      return `${head}\n  (...truncated...)\n${tail}`;
+    }
+    const half = Math.max(0, Math.floor((maxLength - marker.length) / 2));
+    const start = Math.max(0, markerIdx - half);
+    const end = Math.min(html.length, markerIdx + marker.length + half);
+    const prefix = start > 0 ? '(...truncated...)\n' : '';
+    const suffix = end < html.length ? '\n(...truncated...)' : '';
+    return `${prefix}${html.slice(start, end)}${suffix}`;
+  }, []);
+
+  const describeFocusTarget = useCallback((target: FocusTarget) => {
+    const attributeEntries = Object.entries(target.attributes || {}).slice(0, 6);
+    if (attributeEntries.length === 0) {
+      return `<${target.tagName}>`;
+    }
+    const summary = attributeEntries
+      .map(([key, value]) => {
+        const trimmed = value.length > 40 ? `${value.slice(0, 37)}…` : value;
+        return `${key}="${trimmed}"`;
+      })
+      .join(' ');
+    return `<${target.tagName} ${summary}>`;
+  }, []);
+
+  const formatFocusContextBlock = useCallback((target: FocusTarget) => {
+    const descriptor = describeFocusTarget(target);
+    const snippet = truncateHtmlSnippet(target.outerHTML, 1200);
+    const domPath = target.domPath || '(unknown path)';
+    return [
+      'Focus context:',
+      `- Target: ${descriptor}`,
+      `- DOM path: ${domPath}`,
+      '- HTML snippet:',
+      '```html',
+      snippet,
+      '```'
+    ].join('\n');
+  }, [describeFocusTarget, truncateHtmlSnippet]);
+
+  const formatPlacedBlocksContext = useCallback((blocks: PlacedBlock[]) => {
+    if (blocks.length === 0) return '';
+    const lines = [
+      'Semantic blocks to implement:',
+      'The user has placed the following semantic blocks at specific positions in the preview. Each block\'s HTML context below contains an HTML comment marker of the form `<!-- INSERT <block name> HERE -->` at the exact drop position — implement the block at that location. The user chose this position intentionally, so honor it precisely; adapt the block\'s layout and content to fit the surrounding context, and match the existing project\'s styling, colors, fonts, and conventions. Use placeholder/sample content where needed.',
+      '',
+    ];
+    blocks.forEach((placed, index) => {
+      const block = getBlockById(placed.blockId);
+      if (!block) return;
+      lines.push(`[${index + 1}] ${block.name} (page: ${placed.page})`);
+      lines.push(`    Description: ${block.description}`);
+      if (placed.htmlContext) {
+        const marker = `<!-- INSERT ${block.name} HERE -->`;
+        const snippet = truncateHtmlAroundMarker(placed.htmlContext, marker, 1200);
+        lines.push(`    Insert position in context (look for \`${marker}\`):`);
+        lines.push('    ```html');
+        lines.push(`    ${snippet}`);
+        lines.push('    ```');
+      } else {
+        lines.push(`    Position: insert ${placed.position} ${placed.domPath}`);
+      }
+      lines.push('');
+    });
+    return lines.join('\n');
+  }, [truncateHtmlAroundMarker]);
+
+  const handleFocusSelection = useCallback((selection: FocusContextPayload | null) => {
+    if (!selection) {
+      useWorkspaceStore.getState().setFocusContext(null);
+      lastFocusSignatureRef.current = null;
+      return;
+    }
+    const signature = `${selection.domPath || ''}::${selection.tagName || ''}::${selection.outerHTML ? selection.outerHTML.length : 0}`;
+    const now = Date.now();
+    if (lastFocusSignatureRef.current && lastFocusSignatureRef.current.signature === signature && (now - lastFocusSignatureRef.current.timestamp) < 400) {
+      return;
+    }
+    const nextTarget: FocusTarget = {
+      ...selection,
+      timestamp: now
+    };
+    useWorkspaceStore.getState().setFocusContext(nextTarget);
+    toast.info('Focus context set', {
+      description: describeFocusTarget(nextTarget)
+    });
+    lastFocusSignatureRef.current = { signature, timestamp: now };
+  }, [describeFocusTarget]);
+
+  const handlePlacementToggle = useCallback(() => {
+    useWorkspaceStore.getState().setPaletteOpen(!useWorkspaceStore.getState().paletteOpen);
+  }, []);
+
+  const handlePlacementComplete = useCallback((payload: PlacementResult) => {
+    const currentPage = previewRef.current?.getActivePath?.() || '/';
+    useWorkspaceStore.setState(s => ({ placedBlocks: [...s.placedBlocks, {
+      blockId: payload.blockId,
+      placementId: payload.placementId,
+      domPath: payload.domPath,
+      position: payload.position,
+      page: currentPage,
+      htmlContext: payload.htmlContext,
+    }] }));
+  }, []);
+
+  const handleRemovePlacedBlock = useCallback((placementId: string) => {
+    useWorkspaceStore.setState(s => ({ placedBlocks: s.placedBlocks.filter(b => b.placementId !== placementId) }));
+    previewRef.current?.removePlaceholder(placementId);
+  }, []);
+
+  const handleClearPlacedBlocks = useCallback(() => {
+    placedBlocks.forEach(b => previewRef.current?.removePlaceholder(b.placementId));
+    useWorkspaceStore.setState({ placedBlocks: [] });
+  }, [placedBlocks]);
+
+  const handleClosePreview = useCallback(() => {
+    useWorkspaceStore.getState().togglePanel('preview');
+  }, []);
+
+  const handleEnterFullscreen = useCallback(() => {
+    useWorkspaceStore.getState().setFullscreenPreview(true);
+  }, []);
+
+  const handleExitFullscreen = useCallback(() => {
+    useWorkspaceStore.getState().setFullscreenPreview(false);
+  }, []);
+
+  // Listen for showPreview event (dispatched by AI preview command).
+  // Only opens the panel — never toggles it closed if already open.
+  const showPreviewRef = useRef(showPreview);
+  showPreviewRef.current = showPreview;
+  useEffect(() => {
+    const handler = () => {
+      if (!showPreviewRef.current) togglePanel('preview');
+    };
+    window.addEventListener('showPreview', handler);
+    return () => window.removeEventListener('showPreview', handler);
+  }, [togglePanel]);
+
+  const handleSetEntryPoint = useCallback(async (path: string) => {
+    try {
+      const proj = await vfs.getProject(project.id);
+      proj.settings = { ...proj.settings, previewEntryPoint: path };
+      await vfs.updateProject(proj);
+      useWorkspaceStore.getState().updateProjectSettings({ previewEntryPoint: path });
+      toast.success(`Entry point set to ${path}`);
+    } catch (err) {
+      logger.error('Failed to set entry point:', err);
+      toast.error('Failed to set entry point');
+    }
+  }, [project.id]);
+
+  const handleAddPromptFile = useCallback(async () => {
+    try {
+      const { getDomainPrompt } = await import('@/lib/llm/prompts');
+      const runtime = projectRuntime || 'handlebars';
+      await vfs.createFile(project.id, '/.PROMPT.md', getDomainPrompt(runtime));
+      window.dispatchEvent(new CustomEvent('filesChanged', { detail: { projectId: project.id } }));
+      toast.success('.PROMPT.md added to project');
+    } catch (err) {
+      logger.error('Failed to add .PROMPT.md:', err);
+      toast.error('Failed to add .PROMPT.md');
+    }
+  }, [project.id, projectRuntime]);
+
+  const focusPreviewSnippet = focusContext ? truncateHtmlSnippet(focusContext.outerHTML, 240) : '';
+
+  useEffect(() => {
+    const dirty = saveManager.isDirty(project.id);
+    if (dirty) useWorkspaceStore.getState().markDirty();
+    else useWorkspaceStore.getState().markClean();
+    const unsubscribe = saveManager.subscribe(({ projectId, dirty: d }) => {
+      if (projectId === project.id) {
+        if (d) useWorkspaceStore.getState().markDirty();
+        else useWorkspaceStore.getState().markClean();
+      }
+    });
+    return () => unsubscribe();
+  }, [project.id]);
+
+  useEffect(() => {
+    let isMounted = true;
+
+    const initializeWorkspace = async () => {
+      // Dismiss immediately so the generation shelf clears even if async init is slow
+      useWorkspaceStore.getState().dismissGenerationResult(project.id);
+
+      try {
+        // In server mode, check if server has newer version before loading
+        if (process.env.NEXT_PUBLIC_SERVER_MODE === 'true') {
+          try {
+            const { checkServerUpdates, pullServerUpdates, setAutoSyncWorkspaceId } = await import('@/lib/vfs/auto-sync');
+            if (workspaceId) {
+              setAutoSyncWorkspaceId(workspaceId);
+            }
+            const hasUpdates = await checkServerUpdates(project.id);
+            if (hasUpdates) {
+              await pullServerUpdates(project.id, false);
+              logger.debug(`[Workspace] Pulled server updates for project ${project.id}`);
+            }
+          } catch (syncErr) {
+            logger.warn('[Workspace] Server check failed, using local state:', syncErr);
+          }
+        }
+
+        // Skip checkpoint restore if an orchestrator session is active
+        // (generation ran or is running while the workspace was unmounted)
+        if (!useWorkspaceStore.getState().isProjectGenerating(project.id)) {
+          await saveManager.syncProjectSaveState(project.id);
+          const savedCheckpointId = saveManager.getSavedCheckpointId(project.id);
+
+          if (savedCheckpointId) {
+            const exists = await checkpointManager.checkpointExists(savedCheckpointId);
+            if (exists) {
+              const restored = await saveManager.restoreLastSaved(project.id);
+              if (restored) {
+                if (!isMounted) return;
+                useWorkspaceStore.setState({ initialCheckpointId: savedCheckpointId });
+              }
+            } else {
+              // Stale reference — checkpoint was pruned or deleted
+              const proj = await vfs.getProject(project.id);
+              proj.lastSavedCheckpointId = null;
+              await vfs.updateProject(proj);
+            }
+          }
+
+          if (!isMounted) return;
+        }
+
+        const latestProject = await vfs.getProject(project.id);
+        if (!isMounted) return;
+        useWorkspaceStore.getState().initProject(latestProject);
+        if (saveManager.isDirty(project.id)) useWorkspaceStore.getState().markDirty();
+
+        // Ensure a starting-point checkpoint exists so the user can always roll back
+        if (!latestProject.lastSavedCheckpointId) {
+          try {
+            const cp = await checkpointManager.createCheckpoint(project.id, 'Project opened', { kind: 'auto' });
+            latestProject.lastSavedCheckpointId = cp.id;
+            await vfs.updateProject(latestProject);
+            useWorkspaceStore.setState({ initialCheckpointId: cp.id });
+          } catch { /* non-fatal */ }
+        }
+        // Initialize mode from localStorage (migrating the legacy chat-mode key)
+        if (typeof window !== 'undefined') {
+          const storedMode = localStorage.getItem('osw-studio-mode');
+          if (storedMode === 'chat' || storedMode === 'interview' || storedMode === 'code') {
+            useWorkspaceStore.setState({ mode: storedMode });
+          } else if (localStorage.getItem('osw-studio-chat-mode') === 'true') {
+            useWorkspaceStore.setState({ mode: 'chat' });
+            localStorage.setItem('osw-studio-mode', 'chat');
+          }
+        }
+        // Initialize the active interview from localStorage (per project)
+        if (typeof window !== 'undefined') {
+          let restored = null;
+          const stored = localStorage.getItem(`osw-interview-${project.id}`);
+          if (stored) {
+            try {
+              const parsed = JSON.parse(stored);
+              if (parsed && typeof parsed.templateId === 'string' && typeof parsed.title === 'string') {
+                restored = { templateId: parsed.templateId, title: parsed.title };
+              }
+            } catch { /* ignore malformed */ }
+          }
+          useWorkspaceStore.setState({ activeInterview: restored });
+        }
+        // Initialize backendEnabled from localStorage
+        if (migrateBackendKey(project.id)) {
+          useWorkspaceStore.getState().setBackendEnabled(true);
+        }
+
+        logger.debug(`[Workspace] Initializing workspace for project: ${project.id}`);
+
+        // Initialize store persistence and load debug events
+        useWorkspaceStore.getState().initPersistence(project.id);
+        useWorkspaceStore.getState().initLayout();
+        useWorkspaceStore.getState().setCurrentModel(configManager.getDefaultModel());
+        try {
+          await useWorkspaceStore.getState().loadDebugEvents(project.id);
+          if (!isMounted) return;
+        } catch (error) {
+          if (!isMounted) return;
+          logger.error('Failed to load debug events:', error);
+        }
+        useWorkspaceStore.setState({ workspaceReady: true });
+      } catch (error) {
+        if (!isMounted) return;
+        logger.error('Failed to initialize workspace:', error);
+        useWorkspaceStore.setState({ workspaceReady: true });
+      }
+    };
+
+    initializeWorkspace();
+
+    const updateProjectCost = async () => {
+      try {
+        const currentProject = await vfs.getProject(project.id);
+        if (!isMounted) return;
+        if (currentProject?.costTracking?.totalCost) {
+          useWorkspaceStore.getState().setProjectCost(currentProject.costTracking.totalCost);
+        } else {
+          useWorkspaceStore.getState().setProjectCost(0);
+        }
+      } catch {
+        if (!isMounted) return;
+        useWorkspaceStore.getState().setProjectCost(0);
+      }
+    };
+
+    updateProjectCost();
+    const interval = setInterval(updateProjectCost, 2000);
+
+    return () => {
+      isMounted = false;
+      clearInterval(interval);
+    };
+  }, [project.id]);
+
+  useEffect(() => {
+    if (!tourRunning) return;
+
+    if (tourStep === 'provider-settings') {
+      if (typeof window !== 'undefined') {
+        window.dispatchEvent(new CustomEvent('tour-open-provider-settings'));
+      }
+    }
+  }, [tourRunning, tourStep]);
+
+  useEffect(() => {
+    if (!tourRunning) {
+      setWorkspaceHandler(null);
+      return;
+    }
+
+    const handler = async (event: GuidedTourTranscriptEvent) => {
+      // Convert tour events to debug events for ChatPanel display
+      if (event.role === 'clear' && event.action === 'conversation') {
+        await clearDebugEvents();
+        return;
+      }
+
+      if (event.role === 'user') {
+        // User message → conversation_message event
+        await addDebugEvent('conversation_message', {
+          message: {
+            role: 'user',
+            content: event.content
+          }
+        });
+      } else if (event.role === 'assistant') {
+        // Assistant message → conversation_message event
+        const message: any = {
+          role: 'assistant',
+          content: event.content
+        };
+
+        // Store checkpoint ID in UI metadata if present
+        if (event.checkpointId) {
+          message.ui_metadata = {
+            checkpointId: event.checkpointId
+          };
+        }
+
+        await addDebugEvent('conversation_message', { message });
+
+        // Emit checkpoint_created event if checkpoint ID is present
+        if (event.checkpointId) {
+          await addDebugEvent('checkpoint_created', {
+            checkpointId: event.checkpointId,
+            description: `Tour checkpoint: ${event.content.substring(0, 60)}`
+          });
+        }
+      } else if (event.role === 'tool') {
+        // Tool call → simulate tool execution sequence
+        // 1. Tool call initiated
+        const toolCall = {
+          id: `tour-tool-${Date.now()}`,
+          function: {
+            name: event.name,
+            arguments: JSON.stringify({ command: event.command })
+          }
+        };
+
+        await addDebugEvent('toolCalls', {
+          toolCalls: [toolCall]
+        });
+
+        // 2. Tool status (executing)
+        await addDebugEvent('tool_status', {
+          toolId: toolCall.id,
+          name: event.name,
+          status: 'executing'
+        });
+
+        // 3. Tool result
+        await addDebugEvent('tool_result', {
+          toolId: toolCall.id,
+          name: event.name,
+          result: event.output,
+          status: 'completed'
+        });
+
+        // 4. Tool message in conversation
+        await addDebugEvent('conversation_message', {
+          message: {
+            role: 'tool',
+            content: event.output,
+            tool_call_id: toolCall.id
+          }
+        });
+      }
+    };
+
+    setWorkspaceHandler(handler);
+
+    return () => {
+      setWorkspaceHandler(null);
+    };
+  }, [tourRunning, tourStep, tourState.isBusy, setWorkspaceHandler, clearDebugEvents, addDebugEvent]);
+
+  // Clear orchestrator when project changes (chatMode changes handled inside setChatMode action)
+  useEffect(() => {
+    if (!useWorkspaceStore.getState().generating) {
+      useWorkspaceStore.getState().resetOrchestrator();
+    }
+  }, [project.id]);
+
+  // Auto-mount/unmount project backend context based on enabled toggle
+  useEffect(() => {
+    let cancelled = false;
+    if (process.env.NEXT_PUBLIC_SERVER_MODE === 'true' && backendEnabled) {
+      vfs.mountProjectBackendContext(project.id).then(() => {
+        if (!cancelled) {
+          useWorkspaceStore.getState().bumpRefreshTrigger();
+        }
+      });
+    } else {
+      vfs.unmountBackendContext();
+      useWorkspaceStore.getState().bumpRefreshTrigger();
+    }
+    return () => { cancelled = true; };
+  }, [project.id, backendEnabled]);
+
+  // MEMORY CLEANUP: Unload project data from singletons when leaving the workspace
+  // This prevents memory accumulation across project switches
+  useEffect(() => {
+    const projectId = project.id;
+
+    return () => {
+      const thisProjectGenerating = useWorkspaceStore.getState().isProjectGenerating(projectId);
+
+      // Stash foreground events to background buffer before clearing, so the
+      // generation shelf and re-entry can access them.
+      if (thisProjectGenerating) {
+        useWorkspaceStore.getState().stashForegroundEvents(projectId);
+      }
+
+      // Clear caches only if not generating (data still needed for active generation)
+      if (!thisProjectGenerating) {
+        checkpointManager.unloadProject(projectId);
+        debugEventsState.unloadProject(projectId);
+      }
+
+      // Clean up store persistence only if not generating (debounce timer still needed)
+      if (!thisProjectGenerating) {
+        useWorkspaceStore.getState().cleanupPersistence();
+        useWorkspaceStore.getState().resetOrchestrator();
+        useWorkspaceStore.getState().clearDebugEvents();
+      }
+      useWorkspaceStore.getState().resetLayout();
+
+      // Flush any pending sync for this project before leaving
+      vfs.flushSyncTimeout(projectId);
+
+      // Unmount backend context when leaving workspace
+      vfs.unmountBackendContext();
+
+      // Reset project slice state
+      if (!thisProjectGenerating) {
+        useWorkspaceStore.getState().resetProject();
+      } else {
+        // During generation, still reset workspaceReady so the next project shows loading spinners
+        useWorkspaceStore.setState({ workspaceReady: false });
+      }
+
+      logger.debug(`[Workspace] Cleaned up memory for project ${projectId}`);
+    };
+  }, [project.id]);
+
+  // Handle deployment selection change - mount/unmount backend context
+  const handleDeploymentChange = useCallback(async (deploymentId: string | null, deploymentName: string | null) => {
+    useWorkspaceStore.getState().setDeployment(deploymentId);
+
+    // Reset orchestrator so it picks up new backend context on next message
+    useWorkspaceStore.getState().resetOrchestrator();
+
+    if (deploymentId && deploymentName) {
+      await vfs.mountDeploymentRuntimeContext(deploymentId);
+      logger.info(`[Workspace] Connected deployment runtime: ${deploymentName}`);
+    } else {
+      vfs.unmountDeploymentRuntimeContext();
+      logger.info('[Workspace] Disconnected deployment runtime');
+    }
+
+    // Refresh file tree
+    useWorkspaceStore.getState().bumpRefreshTrigger();
+  }, []);
+
+  // Handle backend toggle
+  const handleBackendToggle = useCallback((enabled: boolean) => {
+    useWorkspaceStore.getState().setBackendEnabled(enabled);
+  }, []);
+
+  // Handle project settings updates (runtime, entry point)
+  const handleProjectSettingsUpdate = useCallback((updated: Project) => {
+    useWorkspaceStore.getState().updateProjectSettings({
+      runtime: updated.settings?.runtime,
+      previewEntryPoint: updated.settings?.previewEntryPoint,
+    });
+  }, []);
+
+  const handleFileSelect = useCallback((file: VirtualFile) => {
+    // Check if we're on mobile (matches Tailwind's md breakpoint)
+    const isMobile = window.innerWidth < 768;
+
+    if (isMobile) {
+      // On mobile, switch to editor panel and open file
+      useWorkspaceStore.getState().setActiveMobilePanel('editor');
+      setTimeout(() => {
+        openFileInEditor(file);
+      }, 0);
+    } else {
+      // Desktop behavior remains the same
+      if (!useWorkspaceStore.getState().showEditor) {
+        useWorkspaceStore.getState().togglePanel('editor');
+        setTimeout(() => {
+          openFileInEditor(file);
+        }, 0);
+      } else {
+        openFileInEditor(file);
+      }
+    }
+  }, []);
+
+  const handleFilesChange = useCallback(() => {
+    useWorkspaceStore.getState().bumpRefreshTrigger();
+  }, []);
+
+  const handleSave = useCallback(async () => {
+    if (useWorkspaceStore.getState().saveInProgress) {
+      return;
+    }
+
+    useWorkspaceStore.setState({ saveInProgress: true });
+    try {
+      const checkpoint = await saveManager.save(project.id);
+      const latestProject = await vfs.getProject(project.id);
+
+      useWorkspaceStore.setState({ lastSavedAt: latestProject.lastSavedAt ?? new Date(checkpoint.timestamp) });
+      useWorkspaceStore.getState().incrementCheckpointRefresh();
+      toast.success('Project saved');
+    } catch (error) {
+      logger.error('Failed to save project', error);
+      toast.error('Failed to save project');
+    } finally {
+      useWorkspaceStore.setState({ saveInProgress: false });
+    }
+
+  }, [project.id]);
+
+  const handleCaptureScreenshot = useCallback(async (screenshot: string) => {
+    try {
+      const proj = await vfs.getProject(project.id);
+      proj.previewImage = screenshot;
+      proj.previewUpdatedAt = new Date();
+      await vfs.updateProject(proj);
+      toast.success('Thumbnail updated');
+    } catch (err) {
+      logger.error('Failed to save screenshot:', err);
+      toast.error('Failed to save thumbnail');
+    }
+  }, [project.id]);
+
+  useEffect(() => {
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const isMac = navigator.platform?.toLowerCase().includes('mac');
+      const modifierPressed = isMac ? event.metaKey : event.ctrlKey;
+      if (!modifierPressed) return;
+
+      if (event.key.toLowerCase() === 's') {
+        // Check if Monaco editor has focus - if so, let Monaco handle the save
+        const activeElement = document.activeElement;
+        const isMonacoFocused = activeElement?.closest('.monaco-editor') !== null;
+
+        if (isMonacoFocused) {
+          // Monaco editor will handle file save
+          return;
+        }
+
+        // Otherwise, save the project
+        event.preventDefault();
+        handleSave();
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [handleSave]);
+
+  const handleRestoreCheckpoint = useCallback(async (checkpointId: string, description?: string, options?: { isDiscard?: boolean }) => {
+    try {
+      // First check if checkpoint exists
+      const exists = await checkpointManager.checkpointExists(checkpointId);
+      if (!exists) {
+        toast.error('Checkpoint no longer exists - it may have been cleaned up');
+        logger.warn(`[Workspace] Checkpoint ${checkpointId} no longer exists`);
+        return;
+      }
+
+      const success = await saveManager.runWithSuppressedDirty(project.id, () =>
+        checkpointManager.restoreCheckpoint(checkpointId)
+      );
+      if (success) {
+        toast.success(`Restored to: ${description || 'checkpoint'}`);
+        track(options?.isDiscard ? 'changes_discarded' : 'checkpoint_restore');
+        handleFilesChange();
+
+        const savedId = saveManager.getSavedCheckpointId(project.id);
+        if (savedId && savedId === checkpointId) {
+          saveManager.markClean(project.id);
+          const latestProject = await vfs.getProject(project.id);
+          useWorkspaceStore.setState({ lastSavedAt: latestProject.lastSavedAt ?? null });
+        } else {
+          saveManager.markDirty(project.id);
+        }
+      } else {
+        toast.error('Failed to restore checkpoint');
+      }
+    } catch (error) {
+      logger.error('Error restoring checkpoint:', error);
+      toast.error('Failed to restore checkpoint');
+    }
+  }, [handleFilesChange, project.id]);
+
+  const handleScrollToCheckpoint = useCallback((checkpointId: string) => {
+    if (!useWorkspaceStore.getState().showChat) useWorkspaceStore.getState().togglePanel('chat');
+    requestAnimationFrame(() => {
+      const el = document.querySelector(`[data-checkpoint-id="${checkpointId}"]`);
+      if (el) {
+        el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        el.classList.add('ring-2', 'ring-primary/50');
+        setTimeout(() => el.classList.remove('ring-2', 'ring-primary/50'), 2000);
+      }
+    });
+  }, []);
+
+  const handleRetry = useCallback(async (checkpointId: string) => {
+    try {
+      // First check if checkpoint exists
+      const exists = await checkpointManager.checkpointExists(checkpointId);
+      if (!exists) {
+        toast.error('Checkpoint no longer exists - cannot retry');
+        logger.warn(`[Workspace] Checkpoint ${checkpointId} no longer exists`);
+        return;
+      }
+
+      // Find the user message associated with this checkpoint
+      // Search backwards from the checkpoint to find the most recent user message
+      let userMessageContent = null;
+      const checkpointEventIndex = debugEvents.findIndex(
+        e => e.event === 'checkpoint_created' && e.data?.checkpointId === checkpointId
+      );
+
+      if (checkpointEventIndex >= 0) {
+        // Search backwards from checkpoint event to find user message (in conversation_message events)
+        for (let i = checkpointEventIndex - 1; i >= 0; i--) {
+          if (debugEvents[i].event === 'conversation_message' &&
+              debugEvents[i].data?.message?.role === 'user') {
+            userMessageContent = debugEvents[i].data.message.content;
+            break;
+          }
+        }
+      }
+
+      if (!userMessageContent) {
+        toast.error('Cannot find original user message to retry');
+        logger.warn('[Workspace] No user message found before checkpoint');
+        return;
+      }
+
+      // Find the user message event index to truncate debug events
+      let userMessageIndex = -1;
+      for (let i = checkpointEventIndex - 1; i >= 0; i--) {
+        if (debugEvents[i].event === 'conversation_message' &&
+            debugEvents[i].data?.message?.role === 'user' &&
+            debugEvents[i].data.message.content === userMessageContent) {
+          userMessageIndex = i;
+          break;
+        }
+      }
+
+      if (userMessageIndex === -1) {
+        toast.error('Cannot find user message event to truncate');
+        logger.warn('[Workspace] User message event not found in debug events');
+        return;
+      }
+
+      // Restore the checkpoint
+      const success = await saveManager.runWithSuppressedDirty(project.id, () =>
+        checkpointManager.restoreCheckpoint(checkpointId)
+      );
+      if (!success) {
+        toast.error('Failed to restore checkpoint');
+        return;
+      }
+
+      const savedId = saveManager.getSavedCheckpointId(project.id);
+      if (savedId && savedId === checkpointId) {
+        saveManager.markClean(project.id);
+        const latestProject = await vfs.getProject(project.id);
+        useWorkspaceStore.setState({ lastSavedAt: latestProject.lastSavedAt ?? null });
+      } else {
+        saveManager.markDirty(project.id);
+      }
+
+      // Truncate debug events to remove the user message and all subsequent events
+      // The user message will be re-added by the orchestrator when generation runs
+      const truncatedEvents = debugEvents.slice(0, userMessageIndex);
+      useWorkspaceStore.setState({ debugEvents: truncatedEvents });
+      useWorkspaceStore.getState().resetOrchestrator();
+      await debugEventsState.truncateEvents(project.id, truncatedEvents);
+
+      toast.success('Restored checkpoint and retrying...');
+      handleFilesChange();
+
+      // Retry generation with the original user message.
+      // Use setTimeout so handleGenerate (declared below) is available.
+      setTimeout(() => handleGenerateRef.current?.(userMessageContent), 0);
+
+    } catch (error) {
+      logger.error('Error during retry:', error);
+      toast.error('Failed to retry');
+    }
+  }, [handleFilesChange, project.id, debugEvents]);
+
+  const storeStartGeneration = useWorkspaceStore(s => s.startGeneration);
+
+  const handleGenerate = useCallback(async (promptText?: string, images?: PendingImage[], audio?: PendingAudio[], files?: PendingFile[]) => {
+    // Clear runtime errors
+    useWorkspaceStore.getState().setRuntimeErrors([]);
+
+    let messageContent = (promptText ?? '').trim();
+    const contextParts: string[] = [];
+    if (focusContext) contextParts.push(formatFocusContextBlock(focusContext));
+    if (placedBlocks.length > 0) contextParts.push(formatPlacedBlocksContext(placedBlocks));
+    if (contextParts.length > 0) messageContent = contextParts.join('\n\n') + '\n\n' + messageContent;
+
+    await storeStartGeneration(messageContent, images, {
+      mode,
+      chatMode: mode === 'chat',
+      projectId: project.id,
+      focusContext,
+      placedBlocks,
+      isTourLockingInput,
+      displayPrompt: (promptText ?? '').trim(),
+      // Resuming an interview: keep the template's agenda available so it is
+      // re-injected if the system message ever has to be rebuilt fresh.
+      templateId: mode === 'interview' ? activeInterview?.templateId : undefined,
+      audio,
+      files,
+    });
+
+    // Post-generation UI cleanup
+    handleFilesChange();
+    if (focusContext) useWorkspaceStore.getState().setFocusContext(null);
+    if (placedBlocks.length > 0) {
+      placedBlocks.forEach(b => previewRef.current?.removePlaceholder(b.placementId));
+      useWorkspaceStore.setState({ placedBlocks: [] });
+    }
+  }, [storeStartGeneration, mode, activeInterview, project.id, focusContext, placedBlocks, isTourLockingInput, handleFilesChange, formatFocusContextBlock, formatPlacedBlocksContext]);
+
+  const handleStartInterview = useCallback(async (template: InterviewTemplate) => {
+    if (!project.id) return;
+    track('interview_started', { template: bucketInterviewTemplateId(template.id) });
+    // Start fresh: an interview should not append onto a prior conversation.
+    await useWorkspaceStore.getState().clearChat(project.id);
+    storeSetActiveInterview({ templateId: template.id, title: template.title });
+    await storeStartGeneration(template.title, undefined, {
+      mode: 'interview',
+      projectId: project.id,
+      templateId: template.id,
+    });
+  }, [project.id, storeSetActiveInterview, storeStartGeneration]);
+
+  const handleHandoff = useCallback(async (handoff: InterviewHandoff) => {
+    if (!project.id) return;
+    track('handoff_used', { mode: handoff.mode });
+    // End the interview and start the follow-up task fresh in its target mode.
+    storeSetActiveInterview(null);
+    storeSetMode(handoff.mode);
+    await useWorkspaceStore.getState().clearChat(project.id);
+    await storeStartGeneration(handoff.prompt, undefined, {
+      mode: handoff.mode,
+      chatMode: handoff.mode === 'chat',
+      projectId: project.id,
+    });
+  }, [project.id, storeSetActiveInterview, storeSetMode, storeStartGeneration]);
+
+  handleGenerateRef.current = handleGenerate;
+
+  const stopGeneration = useWorkspaceStore(s => s.stopGeneration);
+  const continueGeneration = useWorkspaceStore(s => s.continueGeneration);
+
+  const handleStop = useCallback(() => {
+    stopGeneration();
+  }, [stopGeneration]);
+
+  const handleContinue = useCallback(() => {
+    continueGeneration();
+  }, [continueGeneration]);
+
+  const handleSendRuntimeErrors = useCallback(() => {
+    const storeErrors = useWorkspaceStore.getState().runtimeErrors;
+    const bufferErrors = drainRuntimeErrors(); // also clears the live buffer
+    const errors = storeErrors.length > 0 ? storeErrors : bufferErrors;
+    if (errors.length === 0) return;
+    useWorkspaceStore.getState().setRuntimeErrors([]);
+    handleGenerate(formatRuntimeErrors(errors));
+  }, [handleGenerate]);
+
+  const handleClearRuntimeErrors = useCallback(() => {
+    drainRuntimeErrors();
+    useWorkspaceStore.getState().setRuntimeErrors([]);
+  }, []);
+
+  const headerActions: HeaderAction[] = [
+    {
+      id: 'back',
+      label: 'Back to projects',
+      icon: ArrowLeft,
+      onClick: guardedBack,
+      variant: 'outline'
+    }
+  ];
+
+  headerActions.push({
+    id: 'save',
+    label: saveInProgress ? 'Saving…' : isDirty ? 'Save' : 'Saved',
+    icon: Save,
+    onClick: handleSave,
+    variant: isDirty ? 'default' : 'outline',
+    disabled: !isDirty || saveInProgress
+  });
+
+  if (initialCheckpointId) {
+    const discardDisabled = saveInProgress || !isDirty;
+    headerActions.push({
+      id: 'discard',
+      label: 'Discard Changes',
+      onClick: () => {},
+      content: (
+        <div className="flex items-center" data-tour-id="discard-changes-button">
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => handleRestoreCheckpoint(initialCheckpointId, 'Last saved state', { isDiscard: true })}
+            disabled={discardDisabled}
+            className="rounded-r-none border-r-0"
+          >
+            <RotateCcw className="h-4 w-4 mr-2" />
+            Discard Changes
+          </Button>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => togglePanel('checkpoints')}
+                onMouseEnter={() => {
+                  if (showCheckpoints) {
+                    useWorkspaceStore.getState().setPanelReplacePreview('checkpoints');
+                  } else {
+                    handleSidebarHover('checkpoints');
+                  }
+                }}
+                onMouseLeave={() => {
+                  useWorkspaceStore.getState().setPanelReplacePreview(null);
+                  useWorkspaceStore.getState().setPanelInsertPreview(null);
+                }}
+                disabled={saveInProgress}
+                className="rounded-l-none px-2"
+                aria-label={showCheckpoints ? 'Close checkpoints panel' : 'Open checkpoints panel'}
+              >
+                {showCheckpoints ? <ChevronUp className="h-4 w-4" /> : <ChevronDown className="h-4 w-4" />}
+              </Button>
+            </TooltipTrigger>
+            <TooltipContent side="bottom">
+              {showCheckpoints ? 'Close checkpoints' : 'All checkpoints'}
+            </TooltipContent>
+          </Tooltip>
+        </div>
+      )
+    });
+  }
+
+  // Desktop header content: Deployment selector + Settings
+  const desktopHeaderContent = (
+    <div className="flex items-center gap-3">
+      {/* Deployment selector for backend context */}
+      <DeploymentSelector
+        projectId={project.id}
+        selectedDeploymentId={selectedDeploymentId}
+        onDeploymentChange={handleDeploymentChange}
+        workspaceId={workspaceId}
+      />
+
+      {/* Project settings button */}
+      <Button
+        variant="outline"
+        size="sm"
+        className="h-8 px-3 flex items-center gap-2"
+        onClick={() => useWorkspaceStore.getState().setShowProjectSettingsModal(true)}
+        title="Project Settings"
+      >
+        <Settings2 className="h-4 w-4" />
+        <span className="text-sm hidden lg:inline">Project</span>
+      </Button>
+
+      {/* Settings popover */}
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button
+            variant="outline"
+            size="sm"
+            className="h-8 px-3 flex items-center gap-2"
+            title="Project cost and settings"
+          >
+            {shouldShowCosts && (
+              <span className="text-sm font-medium">
+                ${projectCost.toFixed(3)}
+              </span>
+            )}
+            <Settings className="h-4 w-4" />
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-[460px] max-h-[min(720px,calc(100vh-5rem))] overflow-hidden flex flex-col" align="end">
+          <SettingsPanel />
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+
+  const mobileMenuContent = (
+    <div className="space-y-2">
+      {shouldShowCosts && (
+        <div className="pb-2 border-b border-border/50">
+          <span className="text-sm font-medium">
+            Project cost: ${projectCost.toFixed(projectCost >= 10 ? 2 : 3)}
+          </span>
+        </div>
+      )}
+      <Button
+        variant="outline"
+        size="sm"
+        className="w-full justify-start"
+        onClick={() => useWorkspaceStore.getState().setShowProjectSettingsModal(true)}
+      >
+        <Settings2 className="h-4 w-4 mr-2" />
+        Project Settings
+      </Button>
+      <Popover>
+        <PopoverTrigger asChild>
+          <Button
+            variant="outline"
+            size="sm"
+            className="w-full justify-start"
+          >
+            <Settings className="h-4 w-4 mr-2" />
+            Settings
+          </Button>
+        </PopoverTrigger>
+        <PopoverContent className="w-[460px] max-w-[calc(100vw-2rem)] max-h-[min(720px,calc(100vh-5rem))] overflow-hidden flex flex-col" align="start">
+          <SettingsPanel />
+        </PopoverContent>
+      </Popover>
+    </div>
+  );
+
+  return (
+    <TooltipProvider>
+      <div className="h-[100dvh] flex flex-col">
+        {/* Header */}
+        <AppHeader
+          leftText={project.name}
+          leftSubtext={{ chat: 'Chat', files: 'Files', editor: 'Editor', preview: 'Preview', checkpoints: 'Checkpoints', console: 'Console', skills: 'Skills', debug: 'Debug' }[activeMobilePanel]}
+          onLogoClick={guardedBack}
+          actions={headerActions}
+          mobileMenuContent={mobileMenuContent}
+          desktopOnlyContent={desktopHeaderContent}
+          mobileVisibleActions={isDirty ? ['save'] : []}
+        />
+
+        {/* Desktop Workspace */}
+        <div className="hidden md:flex flex-1 overflow-hidden bg-background">
+          {/* Left sidebar for panel toggles */}
+          <div className="w-10 bg-muted/70 border-r border-border flex flex-col items-center py-3 gap-1.5">
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  className={`h-5 w-5 px-1 rounded-sm flex items-center justify-center transition-all ${
+                    showChat
+                      ? 'shadow-sm'
+                      : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                  }`}
+                  style={{
+                    backgroundColor: showChat ? 'var(--button-assistant-active)' : undefined,
+                    color: showChat ? 'white' : undefined
+                  }}
+                  onClick={() => togglePanel('chat')}
+                  onMouseEnter={() => handleSidebarHover('chat')}
+                  onMouseLeave={() => handleSidebarHover(null)}
+                >
+                  <MessageSquare className="h-3.5 w-3.5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent
+                side="right"
+                className="border-0"
+                style={{
+                  backgroundColor: 'var(--button-assistant-active)',
+                  color: 'white'
+                }}
+                arrowStyle={{
+                  backgroundColor: 'var(--button-assistant-active)',
+                  fill: 'var(--button-assistant-active)'
+                }}
+              >
+                <p>Chat</p>
+              </TooltipContent>
+            </Tooltip>
+
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  className={`h-5 w-5 px-1 rounded-sm flex items-center justify-center transition-all ${
+                    showFiles
+                      ? 'shadow-sm'
+                      : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                  }`}
+                  style={{
+                    backgroundColor: showFiles ? 'var(--button-files-active)' : undefined,
+                    color: showFiles ? 'white' : undefined
+                  }}
+                  onClick={() => togglePanel('files')}
+                  onMouseEnter={() => handleSidebarHover('files')}
+                  onMouseLeave={() => handleSidebarHover(null)}
+                >
+                  <FolderTree className="h-3.5 w-3.5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent
+                side="right"
+                className="border-0"
+                style={{
+                  backgroundColor: 'var(--button-files-active)',
+                  color: 'white'
+                }}
+                arrowStyle={{
+                  backgroundColor: 'var(--button-files-active)',
+                  fill: 'var(--button-files-active)'
+                }}
+              >
+                <p>File Explorer</p>
+              </TooltipContent>
+            </Tooltip>
+            
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  className={`h-5 w-5 px-1 rounded-sm flex items-center justify-center transition-all ${
+                    showEditor 
+                      ? 'shadow-sm' 
+                      : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                  }`}
+                  style={{
+                    backgroundColor: showEditor ? 'var(--button-editor-active)' : undefined,
+                    color: showEditor ? 'white' : undefined
+                  }}
+                  onClick={() => togglePanel('editor')}
+                  onMouseEnter={() => handleSidebarHover('editor')}
+                  onMouseLeave={() => handleSidebarHover(null)}
+                >
+                  <Code2 className="h-3.5 w-3.5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent 
+                side="right" 
+                className="border-0"
+                style={{ 
+                  backgroundColor: 'var(--button-editor-active)', 
+                  color: 'white'
+                }}
+                arrowStyle={{
+                  backgroundColor: 'var(--button-editor-active)',
+                  fill: 'var(--button-editor-active)'
+                }}
+              >
+                <p>Code Editor</p>
+              </TooltipContent>
+            </Tooltip>
+            
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  className={`h-5 w-5 mx-1 rounded-sm flex items-center justify-center transition-all ${
+                    showPreview
+                      ? 'shadow-sm'
+                      : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                  }`}
+                  style={{
+                    backgroundColor: showPreview ? 'var(--button-preview-active)' : undefined,
+                    color: showPreview ? 'white' : undefined
+                  }}
+                  onClick={() => togglePanel('preview')}
+                  onMouseEnter={() => handleSidebarHover('preview')}
+                  onMouseLeave={() => handleSidebarHover(null)}
+                >
+                  <Eye className="h-3.5 w-3.5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent
+                side="right"
+                className="border-0"
+                style={{
+                  backgroundColor: 'var(--button-preview-active)',
+                  color: 'white'
+                }}
+                arrowStyle={{
+                  backgroundColor: 'var(--button-preview-active)',
+                  fill: 'var(--button-preview-active)'
+                }}
+              >
+                <p>Preview</p>
+              </TooltipContent>
+            </Tooltip>
+
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  className={`h-5 w-5 px-1 rounded-sm flex items-center justify-center transition-all ${
+                    showSkillsPanel
+                      ? 'shadow-sm'
+                      : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                  }`}
+                  style={{
+                    backgroundColor: showSkillsPanel ? 'var(--button-skills-active, #a855f7)' : undefined,
+                    color: showSkillsPanel ? 'white' : undefined
+                  }}
+                  onClick={() => togglePanel('skills')}
+                  onMouseEnter={() => handleSidebarHover('skills')}
+                  onMouseLeave={() => handleSidebarHover(null)}
+                >
+                  <Sparkles className="h-3.5 w-3.5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent
+                side="right"
+                className="border-0"
+                style={{
+                  backgroundColor: 'var(--button-skills-active, #a855f7)',
+                  color: 'white'
+                }}
+                arrowStyle={{
+                  backgroundColor: 'var(--button-skills-active, #a855f7)',
+                  fill: 'var(--button-skills-active, #a855f7)'
+                }}
+              >
+                <p>Skills</p>
+              </TooltipContent>
+            </Tooltip>
+
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  className={`relative h-5 w-5 px-1 rounded-sm flex items-center justify-center transition-all ${
+                    showConsole
+                      ? 'shadow-sm'
+                      : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                  }`}
+                  style={{
+                    backgroundColor: showConsole ? 'var(--button-terminal-active, #22c55e)' : undefined,
+                    color: showConsole ? 'white' : undefined
+                  }}
+                  onClick={() => togglePanel('console')}
+                  onMouseEnter={() => handleSidebarHover('console')}
+                  onMouseLeave={() => handleSidebarHover(null)}
+                >
+                  <TerminalIcon className="h-3.5 w-3.5" />
+                  {hasUnreadConsole && !showConsole && (
+                    <span className="absolute -top-0.5 -right-0.5 h-2 w-2 rounded-full bg-[var(--button-terminal-active,#22c55e)]" />
+                  )}
+                </button>
+              </TooltipTrigger>
+              <TooltipContent
+                side="right"
+                className="border-0"
+                style={{
+                  backgroundColor: 'var(--button-terminal-active, #22c55e)',
+                  color: 'white'
+                }}
+                arrowStyle={{
+                  backgroundColor: 'var(--button-terminal-active, #22c55e)',
+                  fill: 'var(--button-terminal-active, #22c55e)'
+                }}
+              >
+                <p>Console</p>
+              </TooltipContent>
+            </Tooltip>
+
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  className={`h-5 w-5 px-1 rounded-sm flex items-center justify-center transition-all ${
+                    showCheckpoints
+                      ? 'shadow-sm'
+                      : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                  }`}
+                  style={{
+                    backgroundColor: showCheckpoints ? 'var(--button-checkpoint-active)' : undefined,
+                    color: showCheckpoints ? 'white' : undefined
+                  }}
+                  onClick={() => togglePanel('checkpoints')}
+                  onMouseEnter={() => handleSidebarHover('checkpoints')}
+                  onMouseLeave={() => handleSidebarHover(null)}
+                >
+                  <History className="h-3.5 w-3.5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent
+                side="right"
+                className="border-0"
+                style={{
+                  backgroundColor: 'var(--button-checkpoint-active)',
+                  color: 'white'
+                }}
+                arrowStyle={{
+                  backgroundColor: 'var(--button-checkpoint-active)',
+                  fill: 'var(--button-checkpoint-active)'
+                }}
+              >
+                <p>Checkpoints</p>
+              </TooltipContent>
+            </Tooltip>
+
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  className={`h-5 w-5 px-1 rounded-sm flex items-center justify-center transition-all ${
+                    showDebugPanel
+                      ? 'bg-foreground shadow-sm'
+                      : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                  }`}
+                  style={{
+                    color: showDebugPanel ? 'var(--background)' : undefined
+                  }}
+                  onClick={() => togglePanel('debug')}
+                  onMouseEnter={() => handleSidebarHover('debug')}
+                  onMouseLeave={() => handleSidebarHover(null)}
+                >
+                  <Bug className="h-3.5 w-3.5" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent
+                side="right"
+                className="border-0 bg-foreground text-background"
+                arrowStyle={{
+                  backgroundColor: 'var(--foreground)',
+                  fill: 'var(--foreground)'
+                }}
+              >
+                <p>Debug Events</p>
+              </TooltipContent>
+            </Tooltip>
+
+          </div>
+          
+          {/* Main content area — slot-based layout (max 3 panels) */}
+          <div
+            ref={panelContainerRef}
+            className="flex-1 p-2 overflow-hidden"
+            data-tour-id="workspace-panels"
+            onMouseMove={draggingPanel ? handleDragMouseMove : undefined}
+            onMouseUp={draggingPanel ? handlePanelDragEnd : undefined}
+          >
+          <PanelDragProvider value={{ onDragStart: handlePanelDragStart, draggingPanel }}>
+          <ResizablePanelGroup ref={panelGroupRef} direction="horizontal" autoSaveId="workspace-slots">
+            {(() => {
+              // Build ordered list of visible panels using panelOrder
+              const panelMap: Record<string, { minSize: number; content: React.ReactNode }> = {};
+
+              if (showChat) panelMap['chat'] = { minSize: 15, content: (
+                <ChatPanel
+                  events={debugEvents}
+                  onRestore={handleRestoreCheckpoint}
+                  onRetry={handleRetry}
+                  generating={generating}
+                  onGenerate={handleGenerate}
+                  onStop={handleStop}
+                  onContinue={handleContinue}
+                  focusContext={focusContext}
+                  setFocusContext={storeFocusContext}
+                  focusPreviewSnippet={focusPreviewSnippet}
+                  mode={mode}
+                  setMode={storeSetMode}
+                  activeInterview={activeInterview}
+                  onStartInterview={handleStartInterview}
+                  onHandoff={handleHandoff}
+                  currentModel={currentModel}
+                  getModelDisplayName={getModelDisplayName}
+                  isTourLockingInput={isTourLockingInput}
+                  onClearChat={clearDebugEvents}
+                  onClose={() => useWorkspaceStore.getState().togglePanel('chat')}
+                  supportsVision={supportsVision}
+                  inputModalities={inputModalities}
+                  providerReady={providerReady}
+                  runtimeErrors={runtimeErrors}
+                  onSendRuntimeErrors={handleSendRuntimeErrors}
+                  onClearRuntimeErrors={handleClearRuntimeErrors}
+                  placedBlocks={placedBlocks}
+                  onRemovePlacedBlock={handleRemovePlacedBlock}
+                  onClearPlacedBlocks={handleClearPlacedBlocks}
+                />
+              )};
+
+              if (showFiles) panelMap['files'] = { minSize: 14, content: (
+                <div className="h-full border border-border rounded-lg shadow-sm overflow-hidden relative" style={{ background: `linear-gradient(0deg, rgba(var(--panel-files-rgb), 0.01), rgba(var(--panel-files-rgb), 0.01)), var(--card)`, minWidth: '240px' }}>
+                  <FileExplorer
+                    projectId={project.id}
+                    onFileSelect={handleFileSelect}
+                    onClose={() => useWorkspaceStore.getState().togglePanel('files')}
+                    entryPoint={entryPoint}
+                    onSetEntryPoint={handleSetEntryPoint}
+                    onAddPromptFile={handleAddPromptFile}
+                  />
+                </div>
+              )};
+
+              if (showEditor) panelMap['editor'] = { minSize: 20, content: (
+                <div className="h-full border border-border rounded-lg shadow-sm overflow-hidden relative" style={{ background: `linear-gradient(0deg, rgba(var(--panel-editor-rgb), 0.01), rgba(var(--panel-editor-rgb), 0.01)), var(--card)`, minWidth: '240px' }}>
+                  <MultiTabEditor
+                    projectId={project.id}
+                    runtime={projectRuntime}
+                    onClose={() => useWorkspaceStore.getState().togglePanel('editor')}
+                  />
+                </div>
+              )};
+
+              if (showConsole) panelMap['console'] = { minSize: 15, content: (
+                <div className="h-full border border-border rounded-lg shadow-sm overflow-hidden relative" style={{ minWidth: '240px' }}>
+                  <ConsolePanel
+                    projectId={project.id}
+                    runtime={projectRuntime || 'handlebars'}
+                    bufferedMessages={consoleBufferRef.current}
+                    onBufferConsumed={() => { consoleBufferRef.current = []; }}
+                    onClose={() => useWorkspaceStore.getState().togglePanel('console')}
+                  />
+                </div>
+              )};
+
+              if (showPreview) panelMap['preview'] = { minSize: 20, content: (
+                <div
+                  className={fullscreenPreview
+                    ? "fixed inset-0 z-50 bg-background flex flex-col"
+                    : "h-full border border-border rounded-lg shadow-sm overflow-hidden relative"}
+                  style={fullscreenPreview ? undefined : { background: `linear-gradient(0deg, rgba(var(--panel-preview-rgb), 0.01), rgba(var(--panel-preview-rgb), 0.01)), var(--card)`, minWidth: '240px' }}
+                >
+                  <MultipagePreview
+                    ref={previewRef}
+                    projectId={project.id}
+                    refreshTrigger={refreshTrigger}
+                    onFocusSelection={handleFocusSelection}
+                    hasFocusTarget={Boolean(focusContext)}
+                    onClose={fullscreenPreview ? handleExitFullscreen : handleClosePreview}
+                    deploymentId={selectedDeploymentId}
+                    onCaptureScreenshot={handleCaptureScreenshot}
+                    entryPoint={entryPoint}
+                    runtime={projectRuntime}
+                    placementActive={paletteOpen}
+                    onPlacementToggle={handlePlacementToggle}
+                    onPlacementComplete={handlePlacementComplete}
+                    onFullscreen={handleEnterFullscreen}
+                    isFullscreen={fullscreenPreview}
+                  />
+                </div>
+              )};
+
+              if (showCheckpoints) panelMap['checkpoints'] = { minSize: 12, content: (
+                <CheckpointPanel
+                  projectId={project.id}
+                  events={debugEvents}
+                  currentCheckpointId={checkpointManager.getCurrentCheckpoint()?.id}
+                  onRestore={handleRestoreCheckpoint}
+                  onScrollToTurn={handleScrollToCheckpoint}
+                  onClose={() => useWorkspaceStore.getState().togglePanel('checkpoints')}
+                  refreshKey={checkpointRefreshKey}
+                />
+              )};
+
+              if (showDebugPanel) panelMap['debug'] = { minSize: 15, content: (
+                <DebugPanel events={debugEvents} onClear={clearDebugEvents} onClose={() => useWorkspaceStore.getState().togglePanel('debug')} />
+              )};
+
+              if (showSkillsPanel) panelMap['skills'] = { minSize: 10, content: (
+                <SkillsPanel onClose={() => useWorkspaceStore.getState().togglePanel('skills')} />
+              )};
+
+              // Order visible panels by panelOrder
+              const visiblePanels = panelOrder
+                .filter(key => key in panelMap)
+                .map(key => ({ key, ...panelMap[key] }));
+
+              // Render panels with either resize handles (normal) or drop zones (during drag)
+              const elements: React.ReactNode[] = [];
+              const isDragging = !!draggingPanel;
+
+              // Helper: render a drop zone that matches resize handle dimensions (w-2 mx-1)
+              const dropZone = (position: number) => (
+                <div
+                  key={`drop-${position}`}
+                  ref={(el) => registerDropZone(position, el)}
+                  className={`shrink-0 rounded-[3px] border border-dashed animate-expand-indicator ${
+                    dropTarget === position
+                      ? 'bg-primary/40 border-primary/60'
+                      : 'bg-muted/50 border-muted-foreground'
+                  }`}
+                />
+              );
+
+              const dragIdx = isDragging ? visiblePanels.findIndex(p => p.key === draggingPanel) : -1;
+
+              // Insert-position indicator (shown when hovering sidebar to add a panel when there's room)
+              const insertIndicator = (position: number) => (
+                <div
+                  key={`insert-${position}`}
+                  className="shrink-0 rounded-[3px] bg-primary/40 border border-dashed border-primary/60 animate-expand-indicator"
+                />
+              );
+
+              visiblePanels.forEach((panel, idx) => {
+                // Left edge drop zone (before first panel)
+                if (isDragging && idx === 0 && dragIdx !== 0) {
+                  elements.push(dropZone(0));
+                }
+                if (idx > 0) {
+                  if (isDragging) {
+                    const isDroppable = !(idx === dragIdx || idx === dragIdx + 1);
+                    // Hide resize handle inside a collapsing wrapper (animates out as drop zone animates in)
+                    elements.push(
+                      <div key={`handle-wrap-${idx}`} className="animate-collapse-indicator shrink-0 overflow-hidden">
+                        <ResizableHandle key={`handle-${idx}`} withHandle className="pointer-events-none opacity-0" />
+                      </div>
+                    );
+                    if (isDroppable) {
+                      elements.push(dropZone(idx));
+                    } else {
+                      elements.push(<div key={`spacer-${idx}`} className="w-2 mx-1 shrink-0" />);
+                    }
+                  } else {
+                    elements.push(<ResizableHandle key={`handle-${idx}`} withHandle />);
+                  }
+                }
+
+                elements.push(
+                  <ResizablePanel
+                    key={panel.key}
+                    id={`panel-${panel.key}`}
+                    order={idx + 1}
+                    defaultSize={baseSize}
+                    minSize={panel.minSize}
+                  >
+                    <div
+                      className="h-full rounded-lg relative"
+                      data-panel-id={panel.key}
+                    >
+                      {/* Replace-preview / drag highlight overlay — renders on top of panel border */}
+                      {((isDragging && panel.key === draggingPanel) || panelReplacePreview === panel.key) && (
+                        <div
+                          className="absolute inset-0 rounded-lg pointer-events-none z-50"
+                          style={{
+                            border: `1px dashed ${
+                              (isDragging && panel.key === draggingPanel && dropTarget !== null)
+                                ? 'var(--color-muted-foreground)'
+                                : 'var(--color-primary)'
+                            }`,
+                          }}
+                        />
+                      )}
+                      {panel.content}
+                    </div>
+                  </ResizablePanel>
+                );
+
+                // Insert preview after last panel
+                if (!isDragging && panelInsertPreview === idx + 1 && idx === visiblePanels.length - 1) {
+                  elements.push(insertIndicator(idx + 1));
+                }
+              });
+
+              // Right edge drop zone
+              if (isDragging && dragIdx !== visiblePanels.length - 1) {
+                elements.push(dropZone(visiblePanels.length));
+              }
+
+              return elements;
+            })()}
+
+          </ResizablePanelGroup>
+          </PanelDragProvider>
+          </div>
+        </div>
+
+        {/* Mobile Workspace */}
+        <div className="flex md:hidden flex-1 overflow-hidden bg-background flex-col">
+          {/* Single active panel */}
+          <div className="flex-1 pb-12 overflow-hidden">
+            {activeMobilePanel === 'chat' && (
+              <ChatPanel
+                events={debugEvents}
+                onRestore={handleRestoreCheckpoint}
+                onRetry={handleRetry}
+                generating={generating}
+                onGenerate={handleGenerate}
+                onStop={handleStop}
+                onContinue={handleContinue}
+                focusContext={focusContext}
+                setFocusContext={storeFocusContext}
+                focusPreviewSnippet={focusPreviewSnippet}
+                mode={mode}
+                setMode={storeSetMode}
+                activeInterview={activeInterview}
+                onStartInterview={handleStartInterview}
+                onHandoff={handleHandoff}
+                currentModel={currentModel}
+                getModelDisplayName={getModelDisplayName}
+                isTourLockingInput={isTourLockingInput}
+                onClearChat={clearDebugEvents}
+                supportsVision={supportsVision}
+                inputModalities={inputModalities}
+                providerReady={providerReady}
+                runtimeErrors={runtimeErrors}
+                onSendRuntimeErrors={handleSendRuntimeErrors}
+                onClearRuntimeErrors={handleClearRuntimeErrors}
+                placedBlocks={placedBlocks}
+                onRemovePlacedBlock={handleRemovePlacedBlock}
+                onClearPlacedBlocks={handleClearPlacedBlocks}
+              />
+            )}
+
+            {activeMobilePanel === 'files' && (
+              <div className="h-full overflow-hidden relative" style={{ background: `linear-gradient(0deg, rgba(var(--panel-files-rgb), 0.01), rgba(var(--panel-files-rgb), 0.01)), var(--card)` }}>
+                <FileExplorer
+                  projectId={project.id}
+                  onFileSelect={handleFileSelect}
+                  onClose={() => useWorkspaceStore.getState().togglePanel('files')}
+                  entryPoint={entryPoint}
+                  onSetEntryPoint={handleSetEntryPoint}
+                  onAddPromptFile={handleAddPromptFile}
+                />
+              </div>
+            )}
+
+            {activeMobilePanel === 'editor' && (
+              <div className="h-full overflow-hidden relative" style={{ background: `linear-gradient(0deg, rgba(var(--panel-editor-rgb), 0.01), rgba(var(--panel-editor-rgb), 0.01)), var(--card)` }}>
+                <MultiTabEditor
+                  projectId={project.id}
+                  runtime={projectRuntime}
+                  onClose={() => useWorkspaceStore.getState().togglePanel('editor')}
+                />
+              </div>
+            )}
+
+            {activeMobilePanel === 'preview' && (
+              <div className="h-full overflow-hidden relative" style={{ background: `linear-gradient(0deg, rgba(var(--panel-preview-rgb), 0.01), rgba(var(--panel-preview-rgb), 0.01)), var(--card)` }}>
+                <MultipagePreview
+                  ref={previewRef}
+                  projectId={project.id}
+                  refreshTrigger={refreshTrigger}
+                  onFocusSelection={handleFocusSelection}
+                  hasFocusTarget={Boolean(focusContext)}
+                  onClose={handleClosePreview}
+                  deploymentId={selectedDeploymentId}
+                  onCaptureScreenshot={handleCaptureScreenshot}
+                  entryPoint={entryPoint}
+                  runtime={projectRuntime}
+                  placementActive={paletteOpen}
+                  onPlacementToggle={handlePlacementToggle}
+                  onPlacementComplete={handlePlacementComplete}
+                />
+              </div>
+            )}
+
+            {activeMobilePanel === 'checkpoints' && (
+              <div className="h-full overflow-hidden relative">
+                <CheckpointPanel
+                  projectId={project.id}
+                  events={debugEvents}
+                  currentCheckpointId={checkpointManager.getCurrentCheckpoint()?.id}
+                  onRestore={handleRestoreCheckpoint}
+                  onScrollToTurn={handleScrollToCheckpoint}
+                  onClose={() => useWorkspaceStore.getState().setActiveMobilePanel('chat')}
+                  refreshKey={checkpointRefreshKey}
+                />
+              </div>
+            )}
+
+            {activeMobilePanel === 'console' && (
+              <div className="h-full overflow-hidden relative">
+                <ConsolePanel
+                  projectId={project.id}
+                  runtime={projectRuntime || 'handlebars'}
+                  bufferedMessages={consoleBufferRef.current}
+                  onBufferConsumed={() => { consoleBufferRef.current = []; }}
+                />
+              </div>
+            )}
+
+            {activeMobilePanel === 'skills' && (
+              <div className="h-full overflow-hidden relative">
+                <SkillsPanel onClose={() => useWorkspaceStore.getState().setActiveMobilePanel('chat')} />
+              </div>
+            )}
+
+            {activeMobilePanel === 'debug' && (
+              <div className="h-full overflow-hidden relative">
+                <DebugPanel events={debugEvents} onClear={clearDebugEvents} onClose={() => useWorkspaceStore.getState().setActiveMobilePanel('chat')} />
+              </div>
+            )}
+          </div>
+
+          {/* Bottom Navigation Bar */}
+          <div className="fixed bottom-0 left-0 right-0 z-20 bg-card border-t border-border">
+            <div className="flex justify-center items-center p-2 gap-2">
+              <button
+                className={`flex items-center justify-center py-2 px-2 rounded-lg transition-all shadow-sm ${
+                  activeMobilePanel === 'chat'
+                    ? 'text-white'
+                    : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                }`}
+                style={{
+                  backgroundColor: activeMobilePanel === 'chat' ? 'var(--button-assistant-active)' : undefined,
+                }}
+                onClick={() => { useWorkspaceStore.getState().setActiveMobilePanel('chat'); }}
+              >
+                <MessageSquare className="h-4 w-4" />
+              </button>
+
+              <button
+                className={`flex items-center justify-center py-2 px-2 rounded-lg transition-all shadow-sm ${
+                  activeMobilePanel === 'files'
+                    ? 'text-white'
+                    : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                }`}
+                style={{
+                  backgroundColor: activeMobilePanel === 'files' ? 'var(--button-files-active)' : undefined,
+                }}
+                onClick={() => { useWorkspaceStore.getState().setActiveMobilePanel('files'); }}
+              >
+                <FolderTree className="h-4 w-4" />
+              </button>
+
+              <button
+                className={`flex items-center justify-center py-2 px-2 rounded-lg transition-all shadow-sm ${
+                  activeMobilePanel === 'editor'
+                    ? 'text-white'
+                    : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                }`}
+                style={{
+                  backgroundColor: activeMobilePanel === 'editor' ? 'var(--button-editor-active)' : undefined,
+                }}
+                onClick={() => { useWorkspaceStore.getState().setActiveMobilePanel('editor'); }}
+              >
+                <Code2 className="h-4 w-4" />
+              </button>
+
+              <button
+                className={`flex items-center justify-center py-2 px-2 rounded-lg transition-all shadow-sm ${
+                  activeMobilePanel === 'preview'
+                    ? 'text-white'
+                    : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                }`}
+                style={{
+                  backgroundColor: activeMobilePanel === 'preview' ? 'var(--button-preview-active)' : undefined,
+                }}
+                onClick={() => { useWorkspaceStore.getState().setActiveMobilePanel('preview'); }}
+              >
+                <Eye className="h-4 w-4" />
+              </button>
+
+              {/* Overflow menu */}
+              <div className="relative">
+                <button
+                  className={`relative flex items-center justify-center py-2 px-2 rounded-lg transition-all shadow-sm ${
+                    mobileOverflowOpen || ['checkpoints', 'console', 'skills', 'debug'].includes(activeMobilePanel)
+                      ? 'text-white bg-muted'
+                      : 'bg-transparent text-muted-foreground hover:bg-muted/80 hover:text-foreground'
+                  }`}
+                  onClick={() => useWorkspaceStore.getState().setMobileOverflowOpen(!mobileOverflowOpen)}
+                >
+                  <EllipsisVertical className="h-4 w-4" />
+                  {hasUnreadConsole && activeMobilePanel !== 'console' && (
+                    <span className="absolute top-1 right-0.5 h-2 w-2 rounded-full bg-[var(--button-terminal-active,#22c55e)]" />
+                  )}
+                </button>
+
+                {mobileOverflowOpen && (
+                  <>
+                    <div className="fixed inset-0 z-30" onClick={() => useWorkspaceStore.getState().setMobileOverflowOpen(false)} />
+                    <div className="absolute bottom-full right-0 mb-2 z-40 bg-card border border-border rounded-lg shadow-lg py-1 min-w-[140px]">
+                      <button
+                        className={`w-full flex items-center gap-2.5 px-3 py-2 text-sm transition-colors ${
+                          activeMobilePanel === 'checkpoints' ? 'text-white' : 'text-foreground hover:bg-muted'
+                        }`}
+                        style={{
+                          backgroundColor: activeMobilePanel === 'checkpoints' ? 'var(--button-checkpoint-active)' : undefined,
+                        }}
+                        onClick={() => { useWorkspaceStore.getState().setActiveMobilePanel('checkpoints'); }}
+                      >
+                        <History className="h-4 w-4" />
+                        <span>Checkpoints</span>
+                      </button>
+                      <button
+                        className={`w-full flex items-center gap-2.5 px-3 py-2 text-sm transition-colors ${
+                          activeMobilePanel === 'console' ? 'text-white' : 'text-foreground hover:bg-muted'
+                        }`}
+                        style={{
+                          backgroundColor: activeMobilePanel === 'console' ? 'var(--button-terminal-active, #22c55e)' : undefined,
+                        }}
+                        onClick={() => { useWorkspaceStore.getState().setActiveMobilePanel('console'); }}
+                      >
+                        <TerminalIcon className="h-4 w-4" />
+                        <span>Console</span>
+                        {hasUnreadConsole && activeMobilePanel !== 'console' && (
+                          <span className="ml-auto h-2 w-2 rounded-full bg-[var(--button-terminal-active,#22c55e)]" />
+                        )}
+                      </button>
+                      <button
+                        className={`w-full flex items-center gap-2.5 px-3 py-2 text-sm transition-colors ${
+                          activeMobilePanel === 'skills' ? 'text-white' : 'text-foreground hover:bg-muted'
+                        }`}
+                        style={{
+                          backgroundColor: activeMobilePanel === 'skills' ? 'var(--button-skills-active, #a855f7)' : undefined,
+                        }}
+                        onClick={() => { useWorkspaceStore.getState().setActiveMobilePanel('skills'); }}
+                      >
+                        <Sparkles className="h-4 w-4" />
+                        <span>Skills</span>
+                      </button>
+                      <button
+                        className={`w-full flex items-center gap-2.5 px-3 py-2 text-sm transition-colors ${
+                          activeMobilePanel === 'debug' ? 'text-white' : 'text-foreground hover:bg-muted'
+                        }`}
+                        style={{
+                          backgroundColor: activeMobilePanel === 'debug' ? 'var(--button-debug-active, #ef4444)' : undefined,
+                        }}
+                        onClick={() => { useWorkspaceStore.getState().setActiveMobilePanel('debug'); }}
+                      >
+                        <Bug className="h-4 w-4" />
+                        <span>Debug</span>
+                      </button>
+                    </div>
+                  </>
+                )}
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <GuidedTourOverlay location="workspace" />
+      <GuidedTourOverlay location="settings" />
+
+      <ProjectSettingsModal
+        project={project}
+        isOpen={showProjectSettingsModal}
+        onClose={() => useWorkspaceStore.getState().setShowProjectSettingsModal(false)}
+        onProjectUpdate={handleProjectSettingsUpdate}
+        enabled={backendEnabled}
+        onToggleEnabled={handleBackendToggle}
+        workspaceId={workspaceId}
+      />
+
+    </TooltipProvider>
+  );
+}

components/workspace/skills-panel.tsx

@@ -0,0 +1,237 @@
+'use client';
+
+import React, { useState, useEffect, useCallback } from 'react';
+import { Skill, SkillGroup } from '@/lib/vfs/skills/types';
+import { skillsService } from '@/lib/vfs/skills';
+import { vfs } from '@/lib/vfs';
+import { logger } from '@/lib/utils';
+import { Switch } from '@/components/ui/switch';
+import { Button } from '@/components/ui/button';
+import { Sparkles, Plus, FolderTree } from 'lucide-react';
+import { PanelContainer, PanelHeader } from '@/components/ui/panel';
+import {
+  Dialog,
+  DialogContent,
+} from '@/components/ui/dialog';
+import { SkillEditor } from '@/components/skills/SkillEditor';
+
+interface SkillsPanelProps {
+  onClose?: () => void;
+}
+
+export function SkillsPanel({ onClose }: SkillsPanelProps) {
+  const [skills, setSkills] = useState<Skill[]>([]);
+  const [groups, setGroups] = useState<SkillGroup[]>([]);
+  const [globalEnabled, setGlobalEnabled] = useState(true);
+  const [enabledSkills, setEnabledSkills] = useState<Set<string>>(new Set());
+  const [enabledGroups, setEnabledGroups] = useState<Set<string>>(new Set());
+  const [loading, setLoading] = useState(true);
+  const [createDialogOpen, setCreateDialogOpen] = useState(false);
+
+  const loadState = useCallback(async () => {
+    try {
+      const [allSkills, allGroups, global] = await Promise.all([
+        skillsService.getAllSkills(),
+        skillsService.getAllGroups(),
+        skillsService.isGloballyEnabled(),
+      ]);
+      setSkills(allSkills);
+      setGroups(allGroups);
+      setGlobalEnabled(global);
+
+      const enabled = new Set<string>();
+      for (const skill of allSkills) {
+        if (await skillsService.isSkillEnabled(skill.id)) {
+          enabled.add(skill.id);
+        }
+      }
+      setEnabledSkills(enabled);
+
+      const enabledG = new Set<string>();
+      for (const g of allGroups) {
+        if (await skillsService.isGroupEnabled(g.id)) {
+          enabledG.add(g.id);
+        }
+      }
+      setEnabledGroups(enabledG);
+    } catch (err) {
+      logger.error('Failed to load skills:', err);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    loadState();
+  }, [loadState]);
+
+  const handleGlobalToggle = async (enabled: boolean) => {
+    setGlobalEnabled(enabled);
+    await skillsService.setGlobalEnabled(enabled);
+    await vfs.reloadTransientSkills();
+  };
+
+  const handleSkillToggle = async (skillId: string, enabled: boolean) => {
+    const updated = new Set(enabledSkills);
+    if (enabled) {
+      updated.add(skillId);
+      await skillsService.enableSkill(skillId);
+    } else {
+      updated.delete(skillId);
+      await skillsService.disableSkill(skillId);
+    }
+    setEnabledSkills(updated);
+    await vfs.reloadTransientSkills();
+  };
+
+  const handleGroupToggle = async (groupId: string, enabled: boolean) => {
+    const updated = new Set(enabledGroups);
+    if (enabled) {
+      updated.add(groupId);
+      await skillsService.enableGroup(groupId);
+    } else {
+      updated.delete(groupId);
+      await skillsService.disableGroup(groupId);
+    }
+    setEnabledGroups(updated);
+    await vfs.reloadTransientSkills();
+  };
+
+  const builtInSkills = skills.filter(s => s.isBuiltIn);
+  const customSkills = skills.filter(s => !s.isBuiltIn);
+
+  return (
+    <PanelContainer>
+      <PanelHeader
+        icon={Sparkles}
+        title="Skills"
+        color="var(--button-skills-active, #a855f7)"
+        onClose={onClose}
+        panelKey="skills"
+        actions={
+          <Button
+            size="sm"
+            variant="ghost"
+            className="h-6 rounded-full border border-border/60 bg-muted/50 px-2.5 gap-1.5 md:h-5 md:w-5 md:px-0 md:border-0 md:bg-transparent md:rounded-md"
+            onClick={() => setCreateDialogOpen(true)}
+            title="Create new skill"
+          >
+            <Plus className="h-2.5 w-2.5 md:h-3 md:w-3" />
+            <span className="text-xs md:hidden">Add skill</span>
+          </Button>
+        }
+      />
+
+      <div className="flex-1 overflow-y-auto p-3 space-y-4">
+        {/* Global toggle */}
+        <div className="flex items-center justify-between">
+          <div>
+            <div className="text-sm font-medium">Enable skills</div>
+            <p className="text-xs text-muted-foreground mt-0.5">
+              Domain-specific AI instructions
+            </p>
+          </div>
+          <Switch
+            checked={globalEnabled}
+            onCheckedChange={handleGlobalToggle}
+            disabled={loading}
+          />
+        </div>
+
+        {globalEnabled && !loading && (
+          <>
+            {groups.length > 0 && (
+              <div>
+                <div className="flex items-center gap-1.5 mb-2">
+                  <FolderTree className="w-3 h-3 text-muted-foreground" />
+                  <div className="text-xs font-semibold uppercase tracking-wider text-muted-foreground">
+                    Groups
+                  </div>
+                </div>
+                <div className="space-y-0.5">
+                  {groups.map(group => (
+                    <div key={group.id} className="flex items-center justify-between py-1.5 px-2 rounded hover:bg-muted/50">
+                      <div className="flex-1 min-w-0 mr-3">
+                        <div className="text-sm truncate">{group.name}</div>
+                        <div className="text-[10px] text-muted-foreground">
+                          {group.memberIds.length} {group.memberIds.length === 1 ? 'skill' : 'skills'}
+                        </div>
+                      </div>
+                      <Switch
+                        checked={enabledGroups.has(group.id)}
+                        onCheckedChange={(checked) => handleGroupToggle(group.id, checked)}
+                      />
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {builtInSkills.length > 0 && (
+              <div>
+                <div className="text-xs font-semibold uppercase tracking-wider text-muted-foreground mb-2">
+                  Built-in
+                </div>
+                <div className="space-y-0.5">
+                  {builtInSkills.map(skill => (
+                    <div key={skill.id} className="flex items-center justify-between py-1.5 px-2 rounded hover:bg-muted/50">
+                      <div className="flex-1 min-w-0 mr-3">
+                        <div className="text-sm truncate">{skill.name}</div>
+                      </div>
+                      <Switch
+                        checked={enabledSkills.has(skill.id)}
+                        onCheckedChange={(checked) => handleSkillToggle(skill.id, checked)}
+                      />
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {customSkills.length > 0 && (
+              <div>
+                <div className="text-xs font-semibold uppercase tracking-wider text-muted-foreground mb-2">
+                  Custom
+                </div>
+                <div className="space-y-0.5">
+                  {customSkills.map(skill => (
+                    <div key={skill.id} className="flex items-center justify-between py-1.5 px-2 rounded hover:bg-muted/50">
+                      <div className="flex-1 min-w-0 mr-3">
+                        <div className="text-sm truncate">{skill.name}</div>
+                      </div>
+                      <Switch
+                        checked={enabledSkills.has(skill.id)}
+                        onCheckedChange={(checked) => handleSkillToggle(skill.id, checked)}
+                      />
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {skills.length === 0 && (
+              <p className="text-xs text-muted-foreground text-center py-4">
+                No skills available.
+              </p>
+            )}
+          </>
+        )}
+      </div>
+
+      <Dialog open={createDialogOpen} onOpenChange={setCreateDialogOpen}>
+        <DialogContent className="max-w-2xl max-h-[80vh] overflow-y-auto">
+          <SkillEditor
+            skill={null}
+            mode="create"
+            onSave={async () => {
+              setCreateDialogOpen(false);
+              await loadState();
+              await vfs.reloadTransientSkills();
+            }}
+            onCancel={() => setCreateDialogOpen(false)}
+          />
+        </DialogContent>
+      </Dialog>
+    </PanelContainer>
+  );
+}

desktop/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+app/
+dist/

desktop/README.md

@@ -0,0 +1,59 @@
+# OSW Studio Desktop
+
+Electron shell around the OSW Studio Next.js standalone server (full Server
+Mode: SQLite storage, deployments, server functions). This directory is the
+single source of truth for the desktop app — CI releases and local builds both
+use these exact files.
+
+## Layout
+
+- `electron/main.ts` — the entire main process: boots the bundled server,
+  failure diagnostics, consent-based updates, menu
+- `electron/icons/` — committed app icons (no build-time generation)
+- `electron-builder.yml` — packaging config (dmg / nsis / AppImage / deb)
+- `assemble-app.sh` — copies a finished Next.js standalone build into `app/`;
+  shared verbatim by CI and local builds
+- `tsup.config.ts` — compiles `main.ts` into `app/main.js`
+- `package.json` — version is a `0.0.0` placeholder, set at build time from
+  the repo root `package.json`
+
+## Releasing
+
+Releases are built and published by CI (`.github/workflows/desktop-release.yml`),
+triggered by pushing a `desktop-v{version}` tag — normally via
+`release-osw.sh` at the repo parent. The workflow builds all three platforms,
+verifies the complete artifact set, generates release notes from
+`.github/desktop-release-notes.md`, and publishes the GitHub release in a
+single atomic step. If any platform build fails, nothing is published and
+auto-updaters keep serving the previous complete release.
+
+## Local build
+
+From the repo parent directory:
+
+```bash
+./deploy-osw-desktop.sh [mac|win|linux|all]
+```
+
+Or manually from the repo root:
+
+```bash
+NEXT_PUBLIC_SERVER_MODE=true NEXT_PUBLIC_DESKTOP=true npm run build
+./desktop/assemble-app.sh
+cd desktop && npm ci && npm pkg set version=$(node -p "require('../package.json').version")
+npx tsup && npx electron-builder --mac --publish never
+```
+
+## Dev mode
+
+Run `npm run dev` in the repo root, then `npm run dev` in this directory —
+the Electron window points at `localhost:3000` instead of booting the bundled
+server.
+
+## Updates
+
+Updates are consent-based: the app checks GitHub releases on launch and via
+Help → Check for Updates, but only downloads and installs when the user agrees
+(`Download` → `Restart now`). Users can skip a version. On macOS, in-place
+updates require code signing (not set up), so the app links to the releases
+page instead.

desktop/assemble-app.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+
+# Assemble the desktop app/ directory from a completed Next.js standalone build.
+# Shared by CI (.github/workflows/desktop-release.yml) and local builds
+# (deploy-osw-desktop.sh) so the two can never drift.
+#
+# Expects to run from the repo root (osw-studio-git) AFTER:
+#   NEXT_PUBLIC_SERVER_MODE=true NEXT_PUBLIC_DESKTOP=true npm run build
+
+set -e
+
+if [ ! -d ".next/standalone" ]; then
+    echo "Error: .next/standalone not found — run the Next.js build first:"
+    echo "  NEXT_PUBLIC_SERVER_MODE=true NEXT_PUBLIC_DESKTOP=true npm run build"
+    exit 1
+fi
+
+rm -rf desktop/app
+mkdir -p desktop/app
+
+# Standalone server + runtime
+cp -r .next/standalone/. desktop/app/
+
+# Scrub local server-mode state that Next's build-time file tracing can pull
+# into the standalone output on dev machines (the build reads the dev database
+# in Server Mode). Shipping these would leak local data into the installer.
+rm -rf desktop/app/data desktop/app/deployments desktop/app/sites
+
+# Static assets (not included in standalone)
+mkdir -p desktop/app/.next/static
+cp -r .next/static/. desktop/app/.next/static/
+
+# Public files (excluding local sites/deployments)
+cp -r public desktop/app/public
+rm -rf desktop/app/public/sites desktop/app/public/deployments
+
+# Docs for the documentation API
+cp -r docs desktop/app/docs 2>/dev/null || true
+
+echo "Desktop app directory assembled: desktop/app"

desktop/electron-builder.yml

@@ -0,0 +1,64 @@
+appId: com.oswstudio.app
+productName: OSW Studio
+copyright: Copyright © 2026 OSW Studio
+
+directories:
+  output: dist
+  app: app
+
+extraMetadata:
+  main: main.js
+  author:
+    name: OSW Studio
+    email: otst@oswstudio.com
+
+asar: false
+
+files:
+  - "**/*"
+  - "!**/.env"
+  - "!node_modules/@img/sharp-*/**"
+  - "!node_modules/sharp/**"
+
+mac:
+  target:
+    - target: dmg
+      arch:
+        - universal
+  icon: electron/icons/icon.icns
+  category: public.app-category.developer-tools
+  darkModeSupport: true
+  x64ArchFiles: "**/*.node"
+
+dmg:
+  artifactName: OSW-Studio-${version}-${arch}.${ext}
+
+win:
+  target:
+    - nsis
+  icon: electron/icons/icon.png
+
+nsis:
+  oneClick: false
+  allowToChangeInstallationDirectory: true
+  # Explicit, space-free name so the built file, the uploaded GitHub asset, and
+  # the generated latest.yml all agree. The default ("OSW Studio Setup x.y.z.exe")
+  # is sanitized differently by electron-builder (spaces to hyphens in latest.yml)
+  # and by GitHub (spaces to dots in the asset name), which broke the Windows
+  # auto-updater with a 404 on the download URL.
+  artifactName: OSW-Studio-Setup-${version}.${ext}
+
+appImage:
+  artifactName: OSW-Studio-${version}-${arch}.${ext}
+
+linux:
+  target:
+    - AppImage
+    - deb
+  icon: electron/icons/icon.png
+  category: Development
+
+publish:
+  provider: github
+  owner: o-stahl
+  repo: osw-studio

desktop/electron/__tests__/migrate-legacy.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { migrateLegacyDir } from '../migrate-legacy';
+
+let root: string;
+const log = vi.fn();
+
+function legacy(...parts: string[]) { return path.join(root, 'legacy', ...parts); }
+function target(...parts: string[]) { return path.join(root, 'target', ...parts); }
+
+function seedLegacy() {
+  fs.mkdirSync(legacy('workspaces', 'w1'), { recursive: true });
+  fs.writeFileSync(legacy('system.sqlite'), 'system-db');
+  fs.writeFileSync(legacy('workspaces', 'w1', 'osws.sqlite'), 'workspace-db');
+}
+
+beforeEach(() => {
+  root = fs.mkdtempSync(path.join(os.tmpdir(), 'osw-migrate-'));
+  log.mockClear();
+});
+
+afterEach(() => {
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+describe('migrateLegacyDir', () => {
+  it('copies legacy data recursively when the target does not exist', () => {
+    seedLegacy();
+    migrateLegacyDir(legacy(), target(), log);
+
+    expect(fs.readFileSync(target('system.sqlite'), 'utf-8')).toBe('system-db');
+    expect(fs.readFileSync(target('workspaces', 'w1', 'osws.sqlite'), 'utf-8')).toBe('workspace-db');
+    expect(log).toHaveBeenCalledWith(expect.stringContaining('Migrated legacy data'));
+  });
+
+  it('copies when the target exists but is empty (old shells pre-created it)', () => {
+    seedLegacy();
+    fs.mkdirSync(target(), { recursive: true });
+
+    migrateLegacyDir(legacy(), target(), log);
+
+    expect(fs.readFileSync(target('system.sqlite'), 'utf-8')).toBe('system-db');
+  });
+
+  it('never overwrites a target that already has data', () => {
+    seedLegacy();
+    fs.mkdirSync(target(), { recursive: true });
+    fs.writeFileSync(target('system.sqlite'), 'current-db');
+
+    migrateLegacyDir(legacy(), target(), log);
+
+    expect(fs.readFileSync(target('system.sqlite'), 'utf-8')).toBe('current-db');
+    expect(fs.existsSync(target('workspaces'))).toBe(false);
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  it('does nothing when there is no legacy data', () => {
+    migrateLegacyDir(legacy(), target(), log);
+
+    expect(fs.existsSync(target())).toBe(false);
+    expect(log).not.toHaveBeenCalled();
+  });
+
+  it('logs and does not throw when migration fails', () => {
+    seedLegacy();
+    // Target path occupied by a FILE — readdir/copy into it must fail
+    fs.writeFileSync(target(), 'not-a-directory');
+
+    expect(() => migrateLegacyDir(legacy(), target(), log)).not.toThrow();
+    expect(log).toHaveBeenCalledWith(expect.stringContaining('migration failed'));
+  });
+});

desktop/electron/icons/icon.icns

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7404c256bd4ef2b591ed68396c3bb47c5b40ccd41d5e456f35aa1c89642b2e70
+size 382441

desktop/electron/main.ts

@@ -0,0 +1,548 @@
+/**
+ * OSW Studio Desktop — Electron main process.
+ *
+ * Boots the bundled Next.js standalone server (Server Mode) on a free local
+ * port and points a BrowserWindow at it. This file is the single source of
+ * truth for the desktop shell: CI builds (.github/workflows/desktop-release.yml)
+ * and local builds (deploy-osw-desktop.sh) both compile it from here.
+ *
+ * Updates are consent-based: the app checks for new releases and asks before
+ * downloading or installing — it never switches versions on its own.
+ */
+
+import { app, BrowserWindow, Menu, dialog, shell } from 'electron';
+import { autoUpdater } from 'electron-updater';
+import { migrateLegacyDir } from './migrate-legacy';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as http from 'http';
+import * as https from 'https';
+import * as crypto from 'crypto';
+
+const isDev = !app.isPackaged;
+const isMac = process.platform === 'darwin';
+// Headless CI/diagnostic flag: runs the real boot path as a pass/fail command
+// (no window). End users never pass it, so normal launch is unaffected.
+const isSelfTest = process.argv.includes('--self-test') || process.env.OSW_SELFTEST === '1';
+const RELEASES_URL = 'https://github.com/o-stahl/osw-studio/releases/latest';
+const RELEASES_API_URL = 'https://api.github.com/repos/o-stahl/osw-studio/releases/latest';
+
+let mainWindow: BrowserWindow | null = null;
+let serverPort: number | null = null;
+
+// ---------------------------------------------------------------------------
+// Logging — boot/update failures land in userData/logs/main.log so users can
+// attach something useful to bug reports.
+// ---------------------------------------------------------------------------
+
+function logToFile(message: string): void {
+  try {
+    const logDir = path.join(app.getPath('userData'), 'logs');
+    fs.mkdirSync(logDir, { recursive: true });
+    fs.appendFileSync(path.join(logDir, 'main.log'), `[${new Date().toISOString()}] ${message}\n`);
+  } catch {
+    // Logging must never crash the app
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Next.js standalone server
+// ---------------------------------------------------------------------------
+
+async function startNextServer(host: string = 'localhost'): Promise<number> {
+  const { getPort } = await import('get-port-please');
+  const port = await getPort({ portRange: [30011, 50000] });
+
+  process.env.PORT = String(port);
+  process.env.HOSTNAME = host;
+  process.env.NEXT_PUBLIC_APP_URL = `http://${host}:${port}`;
+  process.env.OSW_DESKTOP = 'true';
+
+  // Platform-appropriate writable locations. The install dir is read-only on
+  // Linux (AppImage squashfs) and often on Windows — every server-side path
+  // that defaults to process.cwd() MUST be redirected here. The server reads
+  // DATA_DIR / DEPLOYMENTS_DIR; the CI smoke test asserts this contract.
+  const appDir = app.getAppPath();
+  const dataDir = path.join(app.getPath('userData'), 'data');
+  const deploymentsDir = path.join(app.getPath('userData'), 'deployments');
+
+  // One-time rescue: versions ≤1.75 stored data inside the install directory.
+  // If that data is still reachable (e.g. a Windows update that preserved it),
+  // copy it to userData before first use. Best-effort — on macOS a drag-install
+  // replaces the bundle (and the data inside it) before this code can run.
+  migrateLegacyDir(path.join(appDir, 'data'), dataDir, logToFile);
+  migrateLegacyDir(path.join(appDir, 'deployments'), deploymentsDir, logToFile);
+
+  fs.mkdirSync(dataDir, { recursive: true });
+  process.env.DATA_DIR = dataDir;
+
+  fs.mkdirSync(deploymentsDir, { recursive: true });
+  process.env.DEPLOYMENTS_DIR = deploymentsDir;
+
+  // Security secrets — generated on first launch, persisted across restarts
+  const secretsFile = path.join(app.getPath('userData'), '.secrets.json');
+  let secrets: { sessionSecret: string; encryptionKey: string };
+  try {
+    secrets = JSON.parse(fs.readFileSync(secretsFile, 'utf-8'));
+  } catch {
+    secrets = {
+      sessionSecret: crypto.randomBytes(32).toString('hex'),
+      encryptionKey: crypto.randomBytes(32).toString('base64'),
+    };
+    fs.writeFileSync(secretsFile, JSON.stringify(secrets), { mode: 0o600 });
+  }
+  process.env.SESSION_SECRET = secrets.sessionSecret;
+  process.env.SECRETS_ENCRYPTION_KEY = secrets.encryptionKey;
+  // No admin password for desktop — it's a local single-user app
+
+  // electron-builder's `directories.app: app` flattens the app directory,
+  // so appDir points at the directory containing server.js.
+  process.chdir(appDir);
+  require(path.join(appDir, 'server.js'));
+
+  return port;
+}
+
+async function waitForServer(url: string, maxRetries = 30): Promise<boolean> {
+  for (let i = 0; i < maxRetries; i++) {
+    const ok = await new Promise<boolean>((resolve) => {
+      const req = http.get(url, (res) => { res.resume(); resolve(true); });
+      req.on('error', () => resolve(false));
+      req.setTimeout(2000, () => { req.destroy(); resolve(false); });
+    });
+    if (ok) return true;
+    await new Promise(r => setTimeout(r, 1000));
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Self-test — full headless boot, used by CI and manual distro checks.
+// ---------------------------------------------------------------------------
+
+function postJson(url: string): Promise<{ status: number; body: string }> {
+  return new Promise((resolve, reject) => {
+    const req = http.request(url, { method: 'POST' }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => resolve({ status: res.statusCode || 0, body: data }));
+    });
+    req.on('error', reject);
+    req.setTimeout(15000, () => { req.destroy(new Error('request timed out')); });
+    req.end();
+  });
+}
+
+/**
+ * Boots the real server and drives the workspace-init request, exiting 0/1.
+ * Exercises the native-module/filesystem paths under Electron's ABI that a
+ * system-Node smoke test misses.
+ */
+async function runSelfTest(): Promise<void> {
+  console.log(`[self-test] OSW Studio Desktop v${app.getVersion()} on ${process.platform}/${process.arch}`);
+  console.log(`[self-test] electron=${process.versions.electron} node=${process.versions.node} abi(modules)=${process.versions.modules}`);
+  try {
+    // Bind + probe 127.0.0.1 explicitly: `localhost` can resolve to IPv6 in CI
+    // containers and miss the IPv4-bound server. The shipped app keeps localhost.
+    const port = await startNextServer('127.0.0.1');
+    const base = `http://127.0.0.1:${port}`;
+
+    const ready = await waitForServer(base);
+    if (!ready) {
+      console.error('[self-test] FAIL: server did not respond within the startup timeout');
+      app.exit(1);
+      return;
+    }
+
+    const { status, body } = await postJson(`${base}/api/auth/desktop-init`);
+    let parsed: { workspaceId?: string; error?: string; detail?: string } = {};
+    try { parsed = JSON.parse(body); } catch { /* keep raw body for the log */ }
+
+    if (status === 200 && parsed.workspaceId) {
+      console.log(`[self-test] PASS: workspace initialized (${parsed.workspaceId})`);
+      app.exit(0);
+      return;
+    }
+
+    console.error(`[self-test] FAIL: desktop-init returned HTTP ${status}`);
+    if (parsed.error) console.error(`[self-test] error: ${parsed.error}`);
+    if (parsed.detail) console.error(`[self-test] detail:\n${parsed.detail}`);
+    if (!parsed.error && body) console.error(`[self-test] body: ${body}`);
+    app.exit(1);
+  } catch (err) {
+    console.error(`[self-test] FAIL: ${(err as Error)?.stack || String(err)}`);
+    app.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Failure diagnostics — never leave the user staring at a blank window.
+// ---------------------------------------------------------------------------
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function diagnosticPage(rawTitle: string, rawDetail: string): string {
+  const title = escapeHtml(rawTitle);
+  const detail = escapeHtml(rawDetail);
+  const logPath = escapeHtml(path.join(app.getPath('userData'), 'logs', 'main.log'));
+  const html = `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>OSW Studio — Problem</title>
+<style>
+  body { font-family: system-ui, sans-serif; background: #121212; color: #eaeaea; margin: 0;
+         display: flex; align-items: center; justify-content: center; min-height: 100vh; }
+  .box { max-width: 560px; padding: 2rem; }
+  h1 { font-size: 1.3rem; } p, li { line-height: 1.6; color: #bbb; }
+  code { background: #1e1e1e; padding: 0.1rem 0.4rem; border-radius: 3px; font-size: 0.85em; }
+  a { color: #7aa2f7; }
+</style></head>
+<body><div class="box">
+  <h1>${title}</h1>
+  <p>${detail}</p>
+  <p>OSW Studio Desktop v${app.getVersion()}</p>
+  <ul>
+    <li>Restarting the app usually resolves transient startup problems.</li>
+    <li>If this happened after an update, download the latest installer from the
+        <a href="${RELEASES_URL}" target="_blank">releases page</a> and reinstall — your projects and data are kept.</li>
+    <li>Log file for bug reports: <code>${logPath}</code></li>
+  </ul>
+</div></body></html>`;
+  return `data:text/html;charset=utf-8,${encodeURIComponent(html)}`;
+}
+
+function showDiagnostic(title: string, detail: string): void {
+  logToFile(`${title}: ${detail}`);
+  if (mainWindow && !mainWindow.isDestroyed()) {
+    mainWindow.loadURL(diagnosticPage(title, detail));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Updates — check automatically, but download and install only on user consent.
+// ---------------------------------------------------------------------------
+
+interface UpdatePrefs { skippedVersion?: string }
+
+function updatePrefsFile(): string {
+  return path.join(app.getPath('userData'), 'update-prefs.json');
+}
+
+function readUpdatePrefs(): UpdatePrefs {
+  try {
+    return JSON.parse(fs.readFileSync(updatePrefsFile(), 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeUpdatePrefs(prefs: UpdatePrefs): void {
+  try {
+    fs.writeFileSync(updatePrefsFile(), JSON.stringify(prefs));
+  } catch {
+    // Non-fatal
+  }
+}
+
+function isNewerVersion(candidate: string, current: string): boolean {
+  const a = candidate.split('.').map(n => parseInt(n, 10) || 0);
+  const b = current.split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    if ((a[i] || 0) > (b[i] || 0)) return true;
+    if ((a[i] || 0) < (b[i] || 0)) return false;
+  }
+  return false;
+}
+
+let updaterWired = false;
+let updateDownloaded = false;
+let downloadedVersion = '';
+
+async function promptRestartToUpdate(version: string): Promise<void> {
+  const { response } = await dialog.showMessageBox({
+    type: 'info',
+    title: 'Update ready',
+    message: `OSW Studio v${version} has been downloaded.`,
+    detail: 'Restart now to apply the update, or keep working — it will NOT install until you choose to.',
+    buttons: ['Restart now', 'Later'],
+    defaultId: 0,
+    cancelId: 1,
+  });
+  if (response === 0) {
+    autoUpdater.quitAndInstall();
+  }
+}
+
+async function showUpdateError(err: unknown): Promise<void> {
+  const logPath = path.join(app.getPath('userData'), 'logs', 'main.log');
+  const message = err instanceof Error ? err.message : String(err);
+  const { response } = await dialog.showMessageBox({
+    type: 'error',
+    title: 'Update failed',
+    message: 'The update could not be downloaded.',
+    detail: `${message}\n\nYou can download the latest version manually from the releases page. Details are saved to the log:\n${logPath}`,
+    buttons: ['Open releases page', 'Close'],
+    defaultId: 0,
+    cancelId: 1,
+  });
+  if (response === 0) shell.openExternal(RELEASES_URL);
+}
+
+function wireUpdater(): void {
+  if (updaterWired) return;
+  updaterWired = true;
+
+  autoUpdater.autoDownload = false;
+  autoUpdater.autoInstallOnAppQuit = false;
+
+  // Error dialogs are surfaced at the download call site (which owns the user
+  // interaction); here we only record the error and clear any progress state.
+  autoUpdater.on('error', (err) => {
+    logToFile(`Updater error: ${err?.message || err}`);
+    mainWindow?.setProgressBar(-1);
+  });
+
+  autoUpdater.on('download-progress', (progress) => {
+    mainWindow?.setProgressBar((progress?.percent ?? 0) / 100);
+  });
+
+  autoUpdater.on('update-downloaded', (info) => {
+    mainWindow?.setProgressBar(-1);
+    updateDownloaded = true;
+    downloadedVersion = info.version;
+    void promptRestartToUpdate(info.version);
+  });
+}
+
+/**
+ * Windows/Linux: prompt to download via electron-updater.
+ * interactive = true for menu-triggered checks (always prompts, ignores skips).
+ */
+async function checkForUpdatesElectron(interactive: boolean): Promise<void> {
+  wireUpdater();
+  // An update is already downloaded and waiting — re-offer the restart on
+  // manual checks instead of silently doing nothing.
+  if (updateDownloaded) {
+    if (interactive) await promptRestartToUpdate(downloadedVersion);
+    return;
+  }
+  try {
+    const result = await autoUpdater.checkForUpdates();
+    const version = result?.updateInfo?.version;
+    if (!version || !isNewerVersion(version, app.getVersion())) {
+      if (interactive) {
+        dialog.showMessageBox({ type: 'info', message: 'You are on the latest version.', detail: `OSW Studio v${app.getVersion()}` });
+      }
+      return;
+    }
+    if (!interactive && readUpdatePrefs().skippedVersion === version) return;
+
+    const { response } = await dialog.showMessageBox({
+      type: 'info',
+      title: 'Update available',
+      message: `OSW Studio v${version} is available.`,
+      detail: `You are on v${app.getVersion()}. If you download, it downloads in the background (progress shows on the taskbar) and prompts you to restart when it is ready. It will not install until you choose to.`,
+      buttons: ['Download', 'Skip this version', 'Later'],
+      defaultId: 0,
+      cancelId: 2,
+    });
+    if (response === 0) {
+      logToFile(`Downloading update v${version}`);
+      mainWindow?.setProgressBar(0);
+      autoUpdater.downloadUpdate().catch(err => {
+        mainWindow?.setProgressBar(-1);
+        logToFile(`Update download failed: ${err?.message || err}`);
+        void showUpdateError(err);
+      });
+    } else if (response === 1) {
+      writeUpdatePrefs({ skippedVersion: version });
+    }
+  } catch (err) {
+    logToFile(`Update check failed: ${(err as Error)?.message || err}`);
+    if (interactive) {
+      dialog.showMessageBox({ type: 'warning', message: 'Update check failed.', detail: 'See the log file for details, or check the releases page manually.' });
+    }
+  }
+}
+
+/**
+ * macOS: in-place updates require code signing, which isn't set up — check the
+ * GitHub API for a newer desktop release and point the user at the download.
+ */
+async function checkForUpdatesMac(interactive: boolean): Promise<void> {
+  try {
+    const body = await new Promise<string>((resolve, reject) => {
+      const req = https.get(RELEASES_API_URL, { headers: { 'User-Agent': 'osw-studio-desktop' } }, (res) => {
+        let data = '';
+        res.on('data', (c) => { data += c; });
+        res.on('end', () => resolve(data));
+      });
+      req.on('error', reject);
+      req.setTimeout(10000, () => { req.destroy(); reject(new Error('timeout')); });
+    });
+    const release = JSON.parse(body);
+    const version = String(release.tag_name || '').replace(/^desktop-v/, '');
+    if (!version || !isNewerVersion(version, app.getVersion())) {
+      if (interactive) {
+        dialog.showMessageBox({ type: 'info', message: 'You are on the latest version.', detail: `OSW Studio v${app.getVersion()}` });
+      }
+      return;
+    }
+    if (!interactive && readUpdatePrefs().skippedVersion === version) return;
+
+    const { response } = await dialog.showMessageBox({
+      type: 'info',
+      title: 'Update available',
+      message: `OSW Studio v${version} is available.`,
+      detail: `You are on v${app.getVersion()}. Auto-update is not available on macOS (the app is unsigned) — download the new version from the releases page. Your projects and data are kept.`,
+      buttons: ['Open releases page', 'Skip this version', 'Later'],
+      defaultId: 0,
+      cancelId: 2,
+    });
+    if (response === 0) {
+      shell.openExternal(RELEASES_URL);
+    } else if (response === 1) {
+      writeUpdatePrefs({ skippedVersion: version });
+    }
+  } catch (err) {
+    logToFile(`Update check failed: ${(err as Error)?.message || err}`);
+    if (interactive) {
+      dialog.showMessageBox({ type: 'warning', message: 'Update check failed.', detail: 'Check the releases page manually.' });
+    }
+  }
+}
+
+function checkForUpdates(interactive: boolean): void {
+  if (isDev) return;
+  if (isMac) {
+    void checkForUpdatesMac(interactive);
+  } else {
+    void checkForUpdatesElectron(interactive);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Menu — standard roles plus update actions under Help.
+// ---------------------------------------------------------------------------
+
+function buildMenu(): void {
+  const template: Electron.MenuItemConstructorOptions[] = [
+    ...(isMac ? [{ role: 'appMenu' as const }] : []),
+    { role: 'fileMenu' as const },
+    { role: 'editMenu' as const },
+    { role: 'viewMenu' as const },
+    { role: 'windowMenu' as const },
+    {
+      role: 'help' as const,
+      submenu: [
+        { label: 'Check for Updates…', click: () => checkForUpdates(true) },
+        { label: 'Open Releases Page', click: () => shell.openExternal(RELEASES_URL) },
+        { type: 'separator' as const },
+        { label: 'Report an Issue', click: () => shell.openExternal('https://github.com/o-stahl/osw-studio/issues') },
+        { label: 'Open Logs Folder', click: () => {
+          const logDir = path.join(app.getPath('userData'), 'logs');
+          try { fs.mkdirSync(logDir, { recursive: true }); } catch { /* opening still surfaces the path */ }
+          shell.openPath(logDir);
+        } },
+      ],
+    },
+  ];
+  Menu.setApplicationMenu(Menu.buildFromTemplate(template));
+}
+
+// ---------------------------------------------------------------------------
+// Window
+// ---------------------------------------------------------------------------
+
+async function createWindow(port: number): Promise<void> {
+  mainWindow = new BrowserWindow({
+    width: 1400,
+    height: 900,
+    minWidth: 800,
+    minHeight: 600,
+    title: 'OSW Studio',
+    webPreferences: {
+      nodeIntegration: false,
+      contextIsolation: true,
+    },
+  });
+
+  const serverUrl = `http://localhost:${port}`;
+
+  mainWindow.webContents.on('did-fail-load', (_event, errorCode, errorDescription, validatedURL) => {
+    // -3 (ERR_ABORTED) fires on normal in-app navigation interruptions
+    if (errorCode === -3) return;
+    showDiagnostic('The app failed to load', `${errorDescription} (${errorCode}) while loading ${validatedURL}.`);
+  });
+
+  // Open external links in the default browser
+  mainWindow.webContents.setWindowOpenHandler(({ url }: { url: string }) => {
+    if (url.startsWith('http://localhost')) return { action: 'allow' as const };
+    shell.openExternal(url);
+    return { action: 'deny' as const };
+  });
+
+  mainWindow.on('closed', () => {
+    mainWindow = null;
+  });
+
+  if (!isDev) {
+    const ready = await waitForServer(serverUrl);
+    if (!ready) {
+      showDiagnostic('The local server did not start', 'The bundled server did not respond within 30 seconds.');
+      return;
+    }
+  }
+
+  mainWindow.loadURL(serverUrl);
+
+  if (isDev) {
+    mainWindow.webContents.openDevTools({ mode: 'detach' });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// App lifecycle
+// ---------------------------------------------------------------------------
+
+app.whenReady().then(async () => {
+  if (isSelfTest) {
+    // Headless: boot, probe workspace init, exit. No window, no menu, no updater.
+    await runSelfTest();
+    return;
+  }
+
+  logToFile(`OSW Studio Desktop v${app.getVersion()} starting on ${process.platform}/${process.arch}`);
+  buildMenu();
+  try {
+    if (isDev) {
+      // Dev mode: run `npm run dev` in osw-studio-git and point at it
+      serverPort = 3000;
+    } else {
+      serverPort = await startNextServer();
+    }
+    await createWindow(serverPort);
+    checkForUpdates(false);
+  } catch (error) {
+    const message = (error as Error)?.message || String(error);
+    logToFile(`Failed to start: ${message}`);
+    if (!mainWindow) {
+      mainWindow = new BrowserWindow({ width: 900, height: 600, title: 'OSW Studio' });
+    }
+    mainWindow.loadURL(diagnosticPage('OSW Studio failed to start', message));
+  }
+});
+
+app.on('window-all-closed', () => {
+  app.quit();
+});
+
+app.on('activate', () => {
+  if (mainWindow === null && serverPort) {
+    createWindow(serverPort);
+  }
+});

desktop/electron/migrate-legacy.ts

@@ -0,0 +1,27 @@
+/**
+ * One-time legacy data rescue. Versions ≤1.75 stored data inside the install
+ * directory; if that data is still reachable, copy it to the user-data
+ * location before first use.
+ *
+ * Electron-free so it can be unit tested — the caller injects logging.
+ */
+
+import * as fs from 'fs';
+
+export function migrateLegacyDir(
+  legacyDir: string,
+  targetDir: string,
+  log: (message: string) => void,
+): void {
+  try {
+    // Old shells pre-created the target as an EMPTY directory (without ever
+    // telling the server to use it) — treat empty as absent, or the migration
+    // would never run for anyone who launched an older version.
+    const targetHasData = fs.existsSync(targetDir) && fs.readdirSync(targetDir).length > 0;
+    if (targetHasData || !fs.existsSync(legacyDir)) return;
+    fs.cpSync(legacyDir, targetDir, { recursive: true });
+    log(`Migrated legacy data: ${legacyDir} -> ${targetDir}`);
+  } catch (err) {
+    log(`Legacy data migration failed for ${legacyDir}: ${(err as Error)?.message || err}`);
+  }
+}

desktop/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "osw-studio-desktop",
+  "version": "1.83.0",
+  "private": true,
+  "description": "OSW Studio Desktop — Electron shell around the Next.js standalone server. The version is set at build time from the repo root package.json; 0.0.0 is a placeholder.",
+  "main": "app/main.js",
+  "homepage": "https://github.com/o-stahl/osw-studio",
+  "author": {
+    "name": "OSW Studio",
+    "email": "otst@oswstudio.com"
+  },
+  "scripts": {
+    "compile": "tsup",
+    "typecheck": "tsc --noEmit",
+    "dist:mac": "electron-builder --mac",
+    "dist:win": "electron-builder --win",
+    "dist:linux": "electron-builder --linux",
+    "dev": "tsup && electron ."
+  },
+  "dependencies": {
+    "electron-updater": "^6.3.0",
+    "get-port-please": "^3.1.0"
+  },
+  "devDependencies": {
+    "@electron/rebuild": "^3.7.0",
+    "@types/node": "^20.0.0",
+    "electron": "^34.0.0",
+    "electron-builder": "^25.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.0"
+  }
+}

desktop/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["electron/**/*.ts"],
+  "exclude": ["electron/__tests__"]
+}

desktop/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup';
+
+// Compiles the Electron main process into the assembled app/ directory
+// (created by assemble-app.sh from the Next.js standalone build).
+export default defineConfig({
+  entry: ['electron/main.ts'],
+  outDir: 'app',
+  format: ['cjs'],
+  target: 'node20',
+  platform: 'node',
+  clean: false,
+  external: ['electron', /^next\//],
+  noExternal: ['get-port-please', 'electron-updater'],
+});

docs/BACKEND_FEATURES.md

@@ -0,0 +1,969 @@
+# Backend Features
+
+This guide covers OSW Studio's advanced backend features, available in **Server Mode** only.
+
+## Overview
+
+Server Mode unlocks powerful backend capabilities for your published deployments, including serverless API endpoints, database management, and secure secrets storage.
+
+**Key Features:**
+- **Edge Functions** - REST API endpoints with JavaScript runtime
+- **Database** - Per-deployment SQLite with SQL editor and schema browser
+- **Server Functions** - Reusable helper code for edge functions
+- **Scheduled Functions** - Run edge functions on cron schedules
+- **Secrets** - Encrypted storage for API keys and tokens
+- **Logs** - Execution history and debugging
+- **AI Integration** - AI awareness of backend features via `/.server/` folder
+
+## Where Backend Features Live
+
+Backend features are **project-scoped** — they belong to the project, not to a specific deployment. When you publish the project, its backend features are extracted into the deployment's runtime database. The same project can be published multiple times; each deployment gets a snapshot of the project's backend features at publish time.
+
+You can manage backend features in two places:
+
+1. **Project Settings** (primary, in the workspace): Click **Project Settings** in the workspace header to open a modal with Schema, Functions, Helpers, Secrets, and Schedules tabs. Changes take effect in the project and will be included in the next publish.
+2. **Deployment Server Settings** (for an already-published deployment): Open the deployment in the Admin Dashboard to inspect and tweak the runtime copy of its backend. This is useful for rotating secrets or debugging a published deployment without re-publishing from the project.
+
+## Prerequisites
+
+- OSW Studio running in **Server Mode**
+- A project with Backend enabled (toggle in Project Settings)
+
+## Accessing Server Settings
+
+**From the workspace (recommended):**
+1. Open your project
+2. Click **Project Settings** in the workspace header
+3. Toggle **Backend Enabled** if it isn't already
+4. Use the tabs to create edge functions, server functions, secrets, and schedules
+
+**From the Admin Dashboard (for published deployments):**
+1. Open the **Admin Dashboard** (`/admin`) or `/w/{workspaceId}/deployments`
+2. Navigate to **Deployments** and select your deployment
+3. Click the **Server Settings** button (server icon) next to Deployment Settings
+   - The server icon only appears for published deployments with database enabled
+   - You can also access it via the "..." dropdown menu > "Server Settings"
+
+The Server Settings modal contains seven tabs:
+- **Schema** - Browse tables and columns
+- **SQL** - Execute raw SQL queries
+- **Functions** - Create and manage edge functions (HTTP endpoints)
+- **Helpers** - Create and manage server functions (reusable code)
+- **Secrets** - Store encrypted API keys and tokens
+- **Schedules** - Create and manage scheduled functions (cron jobs)
+- **Logs** - View function execution history
+
+---
+
+## Edge Functions
+
+### Creating a Function
+
+1. Go to **Server Settings > Functions**
+2. Click **New Function**
+3. Configure:
+   - **Name**: Lowercase letters, numbers, and hyphens (e.g., `get-users`)
+   - **HTTP Method**: GET, POST, PUT, DELETE, or ANY
+   - **Description**: Optional description
+   - **Timeout**: 1-30 seconds (default: 5s)
+   - **Code**: JavaScript function body
+
+4. Click **Create Function**
+
+### Function URL
+
+Each function is accessible at:
+```
+https://your-server.com/api/deployments/{deploymentId}/functions/{function-name}
+```
+
+For example:
+```
+https://your-instance.com/api/deployments/abc123/functions/get-products
+```
+
+### Calling Edge Functions from Published Sites
+
+Published sites automatically route edge function calls! Your frontend JavaScript can call functions using simple paths:
+
+```javascript
+// In your published site's JavaScript
+const response = await fetch('/submit-contact', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ name: 'John', email: 'john@example.com' })
+});
+const result = await response.json();
+```
+
+This works because OSW Studio injects a lightweight interceptor script (~1.5KB) into published HTML files that:
+- Detects requests that look like edge function calls (paths without file extensions)
+- Routes them to `/api/deployments/{deploymentId}/functions/{path}`
+- Works with `fetch()`, `XMLHttpRequest`, and form submissions
+
+**Form submissions** are also intercepted:
+```html
+<form action="/submit-contact" method="POST">
+  <input name="email" type="email" required>
+  <button type="submit">Subscribe</button>
+</form>
+```
+
+The form data is automatically converted to JSON and sent to your edge function.
+
+**Custom event handling:**
+```javascript
+// Listen for edge function responses
+document.addEventListener('edge-function-response', (e) => {
+  console.log('Result:', e.detail.result);
+});
+
+document.addEventListener('edge-function-error', (e) => {
+  console.error('Error:', e.detail.error);
+});
+```
+
+### Available APIs
+
+Your function code has access to these global objects:
+
+#### `request` Object
+```javascript
+request.method   // HTTP method (GET, POST, etc.)
+request.body     // Parsed JSON body (POST/PUT/PATCH)
+request.query    // Query string parameters
+request.headers  // Request headers
+request.path     // URL path after function name
+request.params   // Path parameters (if any)
+```
+
+#### `db` Object (Database)
+```javascript
+// Execute SELECT queries
+const users = db.query('SELECT * FROM users WHERE active = ?', [true]);
+const user = db.all('SELECT * FROM users LIMIT 10'); // alias for query
+
+// Execute INSERT/UPDATE/DELETE
+const result = db.run('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);
+// result = { changes: 1 }
+```
+
+#### `Response` Object
+```javascript
+// Return JSON
+Response.json({ users: [...] });
+Response.json({ error: 'Not found' }, 404);
+
+// Return plain text
+Response.text('Hello World');
+Response.text('Created', 201);
+
+// Return error
+Response.error('Something went wrong', 500);
+Response.error('Unauthorized', 401);
+```
+
+#### `fetch` Function
+```javascript
+// Make external HTTP requests
+const response = await fetch('https://api.example.com/data');
+const data = await response.json();
+Response.json(data);
+
+// With options
+const res = await fetch('https://api.example.com/users', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: { name: 'John', email: 'john@example.com' }
+});
+```
+
+**Security Limits:**
+- Max 10 requests per function execution
+- 10 second timeout per request
+- 5MB max response body
+- Only `http://` and `https://` protocols allowed
+- Private IPs blocked in production (localhost, 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 169.254.x.x)
+- Development mode allows local requests for testing
+
+#### `atob` / `btoa` Functions
+```javascript
+// Base64 encode
+const encoded = btoa('Hello World');  // "SGVsbG8gV29ybGQ="
+
+// Base64 decode
+const decoded = atob('SGVsbG8gV29ybGQ=');  // "Hello World"
+```
+
+#### `server` Object (Helper Functions)
+```javascript
+// Call server functions (helpers) defined in the Helpers tab
+const auth = server.validateAuth(request.headers['x-api-key']);
+const formatted = server.formatPrice(29.99, 'USD');
+const user = server.getUserById(123);
+```
+
+See [Server Functions (Helpers)](#server-functions-helpers) for more details.
+
+#### `secrets` Object (Encrypted Secrets)
+```javascript
+// Get secret value by name
+const apiKey = secrets.get('STRIPE_API_KEY');
+if (!apiKey) {
+  Response.error('Stripe not configured', 500);
+  return;
+}
+
+// Check if secret exists
+if (secrets.has('SENDGRID_KEY')) {
+  // Use SendGrid
+}
+
+// List all available secret names
+const allSecrets = secrets.list(); // ['STRIPE_API_KEY', 'SENDGRID_KEY', ...]
+```
+
+See [Secrets](#secrets) for more details.
+
+### Example Functions
+
+#### List Items (GET)
+```javascript
+// GET /api/deployments/{deploymentId}/functions/list-items
+const items = db.query('SELECT * FROM items ORDER BY created_at DESC LIMIT 20');
+Response.json({ items });
+```
+
+#### Create Item (POST)
+```javascript
+// POST /api/deployments/{deploymentId}/functions/create-item
+if (!request.body.name) {
+  Response.error('Name is required', 400);
+  return;
+}
+
+const result = db.run(
+  'INSERT INTO items (name, description) VALUES (?, ?)',
+  [request.body.name, request.body.description || '']
+);
+
+Response.json({
+  id: result.lastInsertRowid,
+  message: 'Item created'
+}, 201);
+```
+
+#### Get Item by ID (GET with path)
+```javascript
+// GET /api/deployments/{deploymentId}/functions/get-item/123
+const id = request.path.split('/')[1];
+if (!id) {
+  Response.error('ID required', 400);
+  return;
+}
+
+const item = db.query('SELECT * FROM items WHERE id = ?', [id]);
+if (item.length === 0) {
+  Response.error('Item not found', 404);
+  return;
+}
+
+Response.json(item[0]);
+```
+
+#### External API Proxy
+```javascript
+// GET /api/deployments/{deploymentId}/functions/weather?city=London
+const city = request.query.city || 'New York';
+const apiKey = secrets.get('WEATHER_API_KEY');
+if (!apiKey) {
+  Response.error('Weather API not configured', 500);
+  return;
+}
+
+const res = await fetch(
+  `https://api.weatherapi.com/v1/current.json?key=${apiKey}&q=${city}`
+);
+const data = await res.json();
+
+Response.json({
+  city: data.location.name,
+  temp: data.current.temp_c,
+  condition: data.current.condition.text
+});
+```
+
+### Security Considerations
+
+#### Sandboxed Execution
+- Functions run in a **QuickJS WebAssembly sandbox** - a completely separate JavaScript engine
+- True isolation via WASM boundary: no shared memory or access to Node.js internals
+- Memory limits enforced by WASM (64MB default)
+- Execution time limits with interrupt handler (configurable 1-30 seconds)
+- Allowed globals: `JSON`, `Date`, `Math`, `Array`, `Object`, `String`, `Number`, `Boolean`, `RegExp`, `Error`, `Map`, `Set`, `Promise`, `Symbol`, `console`
+- Network: `fetch` (with security limits - see above)
+- Utility functions: `parseInt`, `parseFloat`, `isNaN`, `isFinite`, `encodeURIComponent`, `decodeURIComponent`, `encodeURI`, `decodeURI`
+- Base64: `atob` (decode), `btoa` (encode)
+- No access to: `require`, `process`, `__dirname`, `Buffer`, file system
+- `setTimeout`/`setInterval` disabled (prevents runaway execution)
+
+#### Database Protection
+System tables are protected and cannot be accessed:
+- `site_info`
+- `files`
+- `file_tree_nodes`
+- `pageviews`
+- `interactions`
+- `sessions`
+- `edge_functions`
+- `function_logs`
+- `server_functions`
+- `secrets`
+
+Only user-created tables are accessible via the `db` API.
+
+#### Query Limits
+- Maximum 100 database queries per function execution
+- Timeout enforced (1-30 seconds, configurable)
+- SQL keywords validated to prevent dangerous operations
+
+### Managing Functions
+
+#### Enable/Disable
+Click the dropdown menu on a function card and select **Enable** or **Disable**. Disabled functions return 404.
+
+#### Edit
+Click **Edit** in the dropdown to modify the function code, method, or timeout.
+
+#### Delete
+Click **Delete** in the dropdown. This cannot be undone.
+
+#### Copy URL
+Click **Copy URL** below the function card to copy the public endpoint URL.
+
+---
+
+## Server Functions (Helpers)
+
+Server functions are reusable JavaScript helpers that can be called from your edge functions via the `server` object. They enable code reuse across multiple edge functions.
+
+### Creating a Server Function
+
+1. Go to **Server Settings > Helpers**
+2. Click **New Helper**
+3. Configure:
+   - **Name**: Valid JavaScript identifier (camelCase or snake_case, e.g., `validateAuth`, `format_price`)
+   - **Description**: Optional description
+   - **Code**: JavaScript function body
+4. Click **Create Function**
+
+### How Server Functions Work
+
+Server functions receive arguments via an `args` array and have access to `db`, `fetch`, and `console`. They return a value that is passed back to the calling edge function.
+
+```javascript
+// Server function "validateAuth"
+const [apiKey] = args;
+if (!apiKey) {
+  return { valid: false, error: 'No API key provided' };
+}
+
+const users = db.query('SELECT * FROM users WHERE api_key = ?', [apiKey]);
+if (users.length === 0) {
+  return { valid: false, error: 'Invalid API key' };
+}
+
+return { valid: true, user: users[0] };
+```
+
+### Calling from Edge Functions
+
+Server functions are available on the `server` object. Pass arguments as regular function parameters:
+
+```javascript
+// Edge function code
+const auth = server.validateAuth(request.headers['x-api-key']);
+if (!auth.valid) {
+  Response.error(auth.error, 401);
+  return;
+}
+
+// User is authenticated
+const products = db.query(
+  'SELECT * FROM products WHERE user_id = ?',
+  [auth.user.id]
+);
+Response.json({ products });
+```
+
+### Available APIs in Server Functions
+
+| API | Description |
+|-----|-------------|
+| `args` | Array of arguments passed from edge function |
+| `db.query()` | Execute SELECT query |
+| `db.run()` | Execute INSERT/UPDATE/DELETE |
+| `db.all()` | Alias for query |
+| `fetch()` | Make external HTTP requests |
+| `console.log()` | Log messages (visible in function logs) |
+
+### Example Server Functions
+
+#### Validate API Key
+```javascript
+// Name: validateAuth
+const [apiKey] = args;
+if (!apiKey) return { valid: false };
+
+const users = db.query('SELECT id, name, role FROM users WHERE api_key = ?', [apiKey]);
+return users.length > 0 ? { valid: true, user: users[0] } : { valid: false };
+```
+
+#### Format Price
+```javascript
+// Name: formatPrice
+const [amount, currency = 'USD'] = args;
+const symbols = { USD: '$', EUR: '€', GBP: '£', JPY: '¥' };
+const symbol = symbols[currency] || currency + ' ';
+return symbol + amount.toFixed(2);
+```
+
+#### Get User by ID
+```javascript
+// Name: getUserById
+const [id] = args;
+if (!id) return null;
+
+const users = db.query('SELECT * FROM users WHERE id = ?', [id]);
+return users.length > 0 ? users[0] : null;
+```
+
+#### Check Permission
+```javascript
+// Name: hasPermission
+const [userId, permission] = args;
+if (!userId || !permission) return false;
+
+const perms = db.query(
+  'SELECT 1 FROM user_permissions WHERE user_id = ? AND permission = ?',
+  [userId, permission]
+);
+return perms.length > 0;
+```
+
+### Security Notes
+
+- Server functions run in the same QuickJS WASM context as the parent edge function
+- They share the total execution timeout (not additive)
+- Recursive calls are possible but limited by timeout
+- The `server_functions` table is protected and cannot be queried
+- Only enabled server functions are available to edge functions
+
+### Managing Server Functions
+
+- **Enable/Disable**: Toggle from the dropdown menu. Disabled functions are not available to edge functions.
+- **Edit**: Click Edit to modify the code or description
+- **Delete**: Click Delete to remove (cannot be undone)
+
+---
+
+## Secrets
+
+Secrets provide secure, encrypted storage for sensitive values like API keys, tokens, and passwords. Edge functions can access secrets via the `secrets` object without exposing the actual values in your code.
+
+### Prerequisites
+
+Before using secrets, you must set the `SECRETS_ENCRYPTION_KEY` environment variable:
+
+```bash
+# Generate a secure 256-bit key
+node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+
+# Add to your environment
+export SECRETS_ENCRYPTION_KEY="your-generated-key-here"
+```
+
+### Creating a Secret
+
+1. Go to **Server Settings > Secrets**
+2. Click **New Secret**
+3. Configure:
+   - **Name**: SCREAMING_SNAKE_CASE (e.g., `STRIPE_API_KEY`, `SENDGRID_TOKEN`)
+   - **Value**: The secret value (will be encrypted)
+   - **Description**: Optional description
+4. Click **Create Secret**
+
+### Using Secrets in Edge Functions
+
+The `secrets` object is available in all edge functions:
+
+```javascript
+// Get a secret value
+const apiKey = secrets.get('STRIPE_API_KEY');
+
+// Check if a secret exists
+if (secrets.has('STRIPE_API_KEY')) {
+  // Use the secret
+}
+
+// List all available secret names (not values)
+const names = secrets.list(); // ['STRIPE_API_KEY', 'SENDGRID_TOKEN', ...]
+```
+
+### Example: Stripe API Integration
+
+```javascript
+// POST /api/deployments/{deploymentId}/functions/create-charge
+const stripeKey = secrets.get('STRIPE_API_KEY');
+if (!stripeKey) {
+  Response.error('Stripe not configured', 500);
+  return;
+}
+
+const { amount, currency, source } = request.body;
+if (!amount || !source) {
+  Response.error('Amount and source are required', 400);
+  return;
+}
+
+const res = await fetch('https://api.stripe.com/v1/charges', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${stripeKey}`,
+    'Content-Type': 'application/x-www-form-urlencoded',
+  },
+  body: new URLSearchParams({
+    amount: String(amount),
+    currency: currency || 'usd',
+    source,
+  }),
+});
+
+const charge = await res.json();
+Response.json({ charge });
+```
+
+### Secrets API Reference
+
+| Method | Description |
+|--------|-------------|
+| `secrets.get(name)` | Get secret value, or `null` if not found |
+| `secrets.has(name)` | Check if secret exists (returns boolean) |
+| `secrets.list()` | Get array of all secret names (not values) |
+
+### Security Notes
+
+- **Encryption**: Secrets are encrypted using AES-256-GCM with unique IVs per secret
+- **Never logged**: Secret values are never written to logs or exposed in API responses
+- **Admin-only**: Only authenticated admins can create, view (metadata only), or delete secrets
+- **Protected table**: The `secrets` table cannot be queried directly from edge functions
+- **Key management**: The master encryption key must be stored securely as an environment variable
+
+### Managing Secrets
+
+- **Edit**: Click Edit in the dropdown to update the value or description (name cannot be changed)
+- **Delete**: Click Delete to permanently remove (cannot be undone)
+- **No value display**: Secret values are never displayed after creation for security
+
+---
+
+## Scheduled Functions (Cron Jobs)
+
+Scheduled functions run edge functions automatically on a cron schedule. Use them for periodic tasks like database cleanup, report generation, cache warming, or external API syncing.
+
+### Creating a Scheduled Function
+
+1. Go to **Server Settings > Schedules**
+2. Click **New Schedule**
+3. Configure:
+   - **Name**: Lowercase letters, numbers, and hyphens (e.g., `daily-cleanup`)
+   - **Edge Function**: Select which edge function to invoke
+   - **Cron Expression**: Standard 5-field cron syntax (e.g., `0 8 * * *`)
+   - **Timezone**: IANA timezone (default: `UTC`)
+   - **Description**: Optional description
+   - **Config**: Optional JSON object passed as the request body
+4. Click **Create Schedule**
+
+### How It Works
+
+When a scheduled function fires:
+1. The cron scheduler triggers at the specified time
+2. The linked edge function is invoked with the `config` object as `request.body`
+3. The execution result (success/error) and duration are recorded
+4. The next run time is calculated from the cron expression
+
+The edge function runs in the same QuickJS sandbox as HTTP-triggered invocations, with full access to `db`, `fetch`, `secrets`, `server`, and `console`.
+
+### Cron Expression Reference
+
+Cron expressions use 5 fields: `minute hour day-of-month month day-of-week`
+
+**Minimum interval: 5 minutes.** Expressions that resolve to intervals shorter than 5 minutes will be rejected.
+
+| Expression | Description |
+|------------|-------------|
+| `*/5 * * * *` | Every 5 minutes |
+| `0 * * * *` | Every hour (at minute 0) |
+| `0 8 * * *` | Daily at 8:00 AM |
+| `0 0 * * *` | Daily at midnight |
+| `30 9 * * 1-5` | Weekdays at 9:30 AM |
+| `0 0 * * 1` | Every Monday at midnight |
+| `0 0 1 * *` | First of every month at midnight |
+| `0 0 1 1 *` | January 1st at midnight (yearly) |
+
+**Field ranges:**
+- Minute: 0-59
+- Hour: 0-23
+- Day of month: 1-31
+- Month: 1-12
+- Day of week: 0-7 (0 and 7 = Sunday)
+
+### Example Scheduled Functions
+
+#### Daily Database Cleanup
+Clean up old records every day at 3:00 AM UTC:
+
+- **Edge Function** (`cleanup`):
+```javascript
+const daysToKeep = request.body.daysToKeep || 30;
+const cutoff = new Date(Date.now() - daysToKeep * 86400000).toISOString();
+
+const result = db.run('DELETE FROM logs WHERE created_at < ?', [cutoff]);
+Response.json({ deleted: result.changes, cutoff });
+```
+
+- **Schedule config**:
+  - Cron: `0 3 * * *`
+  - Config: `{ "daysToKeep": 30 }`
+
+#### Hourly Stats Aggregation
+Aggregate analytics data every hour:
+
+- **Edge Function** (`aggregate-stats`):
+```javascript
+const hourAgo = new Date(Date.now() - 3600000).toISOString();
+const stats = db.query('SELECT COUNT(*) as views FROM pageviews WHERE timestamp > ?', [hourAgo]);
+
+db.run('INSERT INTO hourly_stats (hour, views) VALUES (?, ?)',
+  [new Date().toISOString().slice(0, 13), stats[0].views]);
+
+Response.json({ aggregated: true, views: stats[0].views });
+```
+
+- **Schedule config**:
+  - Cron: `0 * * * *`
+  - Config: `{}`
+
+#### Weekly Report Email
+Send a weekly summary every Monday at 9:00 AM:
+
+- **Edge Function** (`send-weekly-report`):
+```javascript
+const apiKey = secrets.get('SENDGRID_KEY');
+if (!apiKey) { Response.error('Email not configured', 500); return; }
+
+const stats = db.query('SELECT COUNT(*) as total FROM orders WHERE created_at > datetime("now", "-7 days")');
+
+const res = await fetch('https://api.sendgrid.com/v3/mail/send', {
+  method: 'POST',
+  headers: { 'Authorization': 'Bearer ' + apiKey, 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    personalizations: [{ to: [{ email: request.body.recipient }] }],
+    from: { email: 'reports@example.com' },
+    subject: 'Weekly Report',
+    content: [{ type: 'text/plain', value: 'Orders this week: ' + stats[0].total }]
+  })
+});
+
+Response.json({ sent: res.ok });
+```
+
+- **Schedule config**:
+  - Cron: `0 9 * * 1`
+  - Timezone: `America/New_York`
+  - Config: `{ "recipient": "admin@example.com" }`
+
+### Managing Scheduled Functions
+
+- **Enable/Disable**: Toggle from the dropdown menu. Disabled schedules won't fire.
+- **Edit**: Click Edit to modify the cron expression, linked function, timezone, or config.
+- **Delete**: Click Delete to remove (cannot be undone).
+- **Status tracking**: Each schedule card shows the next run time, last run status (success/error), and last run time.
+
+---
+
+## SQL Editor
+
+The SQL Editor allows direct SQL query execution against your deployment's database.
+
+### Executing Queries
+
+1. Go to **Server Settings > SQL**
+2. Type your SQL query in the editor
+3. Click **Execute** or press `Ctrl/Cmd + Enter`
+4. View results in the table below
+
+### Query History
+
+The editor maintains a history of your last 20 queries (stored in browser localStorage).
+
+Click **History** to view and re-run previous queries.
+
+### Supported Operations
+
+```sql
+-- SELECT queries
+SELECT * FROM products WHERE price > 100;
+SELECT COUNT(*) FROM orders;
+
+-- INSERT
+INSERT INTO products (name, price) VALUES ('Widget', 29.99);
+
+-- UPDATE
+UPDATE products SET price = 24.99 WHERE id = 1;
+
+-- DELETE
+DELETE FROM products WHERE discontinued = 1;
+
+-- CREATE TABLE
+CREATE TABLE products (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  name TEXT NOT NULL,
+  price REAL DEFAULT 0,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- ALTER TABLE
+ALTER TABLE products ADD COLUMN stock INTEGER DEFAULT 0;
+
+-- DROP TABLE (use with caution!)
+DROP TABLE old_products;
+```
+
+### Query Safety
+
+- System tables are accessible (read-only for some operations)
+- All queries are executed with full permissions - use caution!
+- No automatic transaction management - consider wrapping related operations
+
+---
+
+## Schema Viewer
+
+The Schema Viewer displays your database structure.
+
+### Viewing Tables
+
+1. Go to **Server Settings > Schema**
+2. Click on a table name to expand and view columns
+3. Each column shows: name, type, nullable, default value, primary key status
+
+### System Tables
+
+Toggle **Show System Tables** to view OSW Studio's internal tables:
+- `site_info` - Deployment metadata
+- `files` - File contents
+- `file_tree_nodes` - File tree structure
+- `pageviews` / `interactions` / `sessions` - Analytics data
+- `edge_functions` - Function definitions
+- `function_logs` - Execution logs
+
+System tables are marked with a "(system)" label.
+
+---
+
+## Execution Logs
+
+View function execution history in the **Logs** tab.
+
+### Log Information
+
+Each log entry shows:
+- **Status**: Success (2xx), redirect (3xx), or error (4xx/5xx)
+- **Function**: Function name
+- **Method**: HTTP method used
+- **Path**: Request path
+- **Duration**: Execution time in milliseconds
+- **Time**: Timestamp
+
+### Managing Logs
+
+- Click **Refresh** to load latest logs
+- Click **Clear** to delete all logs (cannot be undone)
+- Logs are limited to the most recent 200 entries
+
+---
+
+## Best Practices
+
+### Function Design
+
+1. **Keep functions focused** - One function per operation
+2. **Validate input** - Check `request.body` and `request.query` before use
+3. **Handle errors** - Return appropriate HTTP status codes
+4. **Use meaningful names** - `create-order` not `func1`
+
+### Database Usage
+
+1. **Use parameterized queries** - Prevents SQL injection
+   ```javascript
+   // Good
+   db.query('SELECT * FROM users WHERE id = ?', [userId]);
+
+   // Bad - SQL injection risk!
+   db.query(`SELECT * FROM users WHERE id = ${userId}`);
+   ```
+
+2. **Create indexes** for frequently queried columns:
+   ```sql
+   CREATE INDEX idx_orders_user_id ON orders(user_id);
+   ```
+
+3. **Limit result sets** to avoid memory issues:
+   ```javascript
+   db.query('SELECT * FROM products LIMIT 100');
+   ```
+
+### Performance
+
+1. **Set appropriate timeouts** - Don't use 30s if 5s is sufficient
+2. **Minimize external requests** - Each `fetch()` adds latency
+3. **Cache when possible** - Store API responses in your database
+
+---
+
+## Troubleshooting
+
+### Function Returns 404
+- Check that the function is **enabled**
+- Verify the function name in the URL is correct
+- Ensure the deployment is published and has database enabled
+
+### Function Returns 500
+- Check the **Logs** tab for error details
+- Verify your SQL queries are valid
+- Ensure external APIs are responding
+
+### Query Execution Failed
+- Check SQL syntax
+- Verify table and column names
+- Look for constraint violations (unique, foreign key)
+
+### Cannot Access Table
+- System tables are protected in edge functions
+- Use the SQL Editor for system table access
+
+---
+
+## API Reference
+
+### Public Endpoints
+
+| Method | URL | Description |
+|--------|-----|-------------|
+| * | `/api/deployments/{deploymentId}/functions/{name}` | Invoke edge function |
+| * | `/api/deployments/{deploymentId}/functions/{name}/*` | Invoke with path params |
+
+### Admin Endpoints (Requires Authentication)
+
+| Method | URL | Description |
+|--------|-----|-------------|
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/functions` | List edge functions |
+| POST | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/functions` | Create edge function |
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/functions/{id}` | Get edge function |
+| PUT | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/functions/{id}` | Update edge function |
+| DELETE | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/functions/{id}` | Delete edge function |
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/server-functions` | List server functions |
+| POST | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/server-functions` | Create server function |
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/server-functions/{id}` | Get server function |
+| PUT | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/server-functions/{id}` | Update server function |
+| DELETE | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/server-functions/{id}` | Delete server function |
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/scheduled-functions` | List scheduled functions |
+| POST | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/scheduled-functions` | Create scheduled function |
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/scheduled-functions/{id}` | Get scheduled function |
+| PUT | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/scheduled-functions/{id}` | Update scheduled function |
+| DELETE | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/scheduled-functions/{id}` | Delete scheduled function |
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/secrets` | List secrets (metadata only) |
+| POST | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/secrets` | Create secret |
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/secrets/{id}` | Get secret (metadata only) |
+| PUT | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/secrets/{id}` | Update secret |
+| DELETE | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/secrets/{id}` | Delete secret |
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/database/schema` | Get schema |
+| POST | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/database/query` | Execute SQL |
+| GET | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/database/logs` | Get logs |
+| DELETE | `/api/w/{workspaceId}/admin/deployments/{deploymentId}/database/logs` | Clear logs |
+
+---
+
+## AI Integration
+
+OSW Studio's AI assistant can understand and work with your backend features when you select a deployment in the workspace.
+
+### How It Works
+
+1. **Project Backend Context** - When the project has Backend Enabled, its edge functions, helpers, secrets, schedules, and schema are mounted automatically in `/.server/`
+2. **Optional Deployment Overlay** - Selecting a deployment in the workspace header additionally layers in that deployment's runtime state (published functions, live schema, etc.)
+3. **AI Awareness** - The AI receives information about available:
+   - Edge functions (endpoints, methods)
+   - Database schema (tables, columns)
+   - Server functions (helpers)
+   - Scheduled functions (cron schedules)
+   - Secrets (names only, not values)
+
+### The `/.server/` Folder
+
+When a deployment is selected, a hidden `/.server/` folder appears in the file explorer containing:
+
+| Folder | Contents |
+|--------|----------|
+| `edge-functions/*.json` | Edge function endpoints |
+| `server-functions/*.json` | Helper functions |
+| `scheduled-functions/*.json` | Cron schedules |
+| `secrets/*.json` | Secret names (not values) |
+| `db/schema.sql` | Database schema |
+
+These files reflect the project's backend feature state:
+- **Schema** (`db/schema.sql`) is read-only — edit schema by running SQL in Project Settings or via the AI's `sqlite3` shell command
+- **Functions, helpers, secrets, and schedules** can be created and edited by the AI using shell commands. Changes update the corresponding records in the project's database
+
+Files are transient in the sense that they're regenerated from the project's backend state — you don't commit them manually.
+
+### Using AI with Backend Features
+
+**Example prompts:**
+
+```
+What tables are in the database?
+```
+
+```
+Create an edge function to list all products
+```
+
+```
+I need an endpoint that validates API keys using the STRIPE_KEY secret
+```
+
+```
+Create a scheduled function to clean up old records every night
+```
+
+```
+Help me design a schema for a blog with posts and comments
+```
+
+The AI can:
+- Read and explain your current schema
+- Suggest edge function implementations
+- Reference available secrets by name
+- Help design database structures
+- Debug function issues
+
+### Viewing Hidden Files
+
+To see the `/.server/` folder:
+1. Right-click in the File Explorer
+2. Select **Show Hidden Files**
+3. Look for the folder with the orange server icon
+
+See also: **[Server Mode > Server Context Integration](?doc=server-mode#server-context-integration)**

docs/CUSTOM_DOMAINS.md

@@ -0,0 +1,54 @@
+# Custom Domains
+
+## Setup (2 steps)
+
+1. In OSW Studio, go to Deployment Settings and enter your domain (e.g., `sweetcandies.com`)
+2. In your DNS provider, add an A record pointing to your OSW Studio server's IP address
+
+That's it. The server handles SSL certificates automatically via Let's Encrypt.
+
+## How It Works
+
+When you publish a deployment with a custom domain:
+
+1. OSW Studio registers the domain in its routing table
+2. The reverse proxy (Caddy) intercepts requests to your domain
+3. Caddy provisions an SSL certificate automatically (on-demand TLS)
+4. Requests are routed to your deployment's static files
+5. `/api/` paths (edge functions, analytics) pass through without rewriting
+
+## What OSW Studio Handles
+
+- Domain registration in the routing table
+- Root-relative asset paths when a custom domain is set
+- SEO meta tags, sitemaps, and canonical URLs using your domain
+- Analytics origin validation for your domain
+
+## What OSW Studio Does Not Handle
+
+- DNS configuration (you add the A record)
+- SSL certificates (Caddy handles this automatically)
+- Domain purchase or registration
+
+## For Self-Hosted Instances
+
+Your OSW Studio instance needs a reverse proxy with TLS support. See `docs/SELF_HOSTED_DOMAINS.md` for API endpoints and proxy requirements.
+
+## For Hosted Instances (oswstudio.com)
+
+Custom domains are handled automatically by the platform. Just add your DNS A record.
+
+## Troubleshooting
+
+**Site not loading after adding DNS**
+- DNS propagation can take up to 48 hours (usually minutes)
+- Verify your A record: `dig sweetcandies.com` should show the server IP
+- The first request may take a few seconds while the SSL certificate is provisioned
+
+**SSL certificate not working**
+- Ensure your DNS A record points directly to the server IP (not through a proxy)
+- Caddy needs port 80 and 443 open for Let's Encrypt HTTP-01 challenges
+
+**Assets loading from wrong path**
+- Republish your deployment after setting the custom domain
+- The asset path rewriting only takes effect on publish