From ed7e7cd8f558234f42badb02d4e3951680f0e290 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 15 Sep 2026 03:07:45 +0530
Subject: [PATCH 1/9] feat(local): pick a base URL from common endpoints when
 adding a connection

---
 .../frontend/src/components/ui/combobox.tsx   | 431 ++++++++++++++++++
 .../src/components/ui/input-group.tsx         | 136 ++++++
 .../model-selection/connection-form.tsx       |  78 +++-
 3 files changed, 640 insertions(+), 5 deletions(-)
 create mode 100644 surfsense_local/frontend/src/components/ui/combobox.tsx
 create mode 100644 surfsense_local/frontend/src/components/ui/input-group.tsx

diff --git a/surfsense_local/frontend/src/components/ui/combobox.tsx b/surfsense_local/frontend/src/components/ui/combobox.tsx
new file mode 100644
index 0000000000..fcef3a5f8b
--- /dev/null
+++ b/surfsense_local/frontend/src/components/ui/combobox.tsx
@@ -0,0 +1,431 @@
+import * as React from "react"
+import { Popover as PopoverPrimitive } from "radix-ui"
+
+import { CheckIcon, ChevronDownIcon } from "@/components/ui/icons"
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from "@/components/ui/input-group"
+import { cn } from "@/lib/utils"
+
+// shadcn ships its Combobox on Base UI, which this app does not depend on, so
+// the same API is rebuilt here on the Radix Popover the rest of the UI uses.
+type ComboboxFilter = (
+  itemValue: string,
+  query: string,
+  keywords: string[]
+) => boolean
+
+const defaultFilter: ComboboxFilter = (itemValue, query, keywords) => {
+  const needle = query.trim().toLowerCase()
+  if (!needle) return true
+  return [itemValue, ...keywords].some((candidate) =>
+    candidate.toLowerCase().includes(needle)
+  )
+}
+
+type ComboboxContextValue = {
+  open: boolean
+  setOpen: (open: boolean) => void
+  value: string | null
+  select: (value: string) => void
+  inputValue: string
+  setInputValue: (value: string) => void
+  disabled: boolean
+  matches: (itemValue: string, keywords: string[]) => boolean
+  register: (itemValue: string, keywords: string[]) => () => void
+  visibleCount: number
+  listId: string
+  activeId: string | null
+  setActiveId: (id: string | null) => void
+  itemId: (itemValue: string) => string
+  listRef: React.RefObject<HTMLDivElement | null>
+}
+
+const ComboboxContext = React.createContext<ComboboxContextValue | null>(null)
+
+function useCombobox(part: string) {
+  const context = React.useContext(ComboboxContext)
+  if (!context) {
+    throw new Error(`${part} must be used within a Combobox`)
+  }
+  return context
+}
+
+function Combobox({
+  children,
+  value,
+  onValueChange,
+  inputValue,
+  onInputValueChange,
+  open: openProp,
+  onOpenChange,
+  filter = defaultFilter,
+  disabled = false,
+}: {
+  children: React.ReactNode
+  value?: string | null
+  onValueChange?: (value: string) => void
+  inputValue: string
+  onInputValueChange: (value: string) => void
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  filter?: ComboboxFilter
+  disabled?: boolean
+}) {
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(false)
+  const [activeId, setActiveId] = React.useState<string | null>(null)
+  const [items, setItems] = React.useState<Record<string, string[]>>({})
+  const listRef = React.useRef<HTMLDivElement>(null)
+  const listId = React.useId()
+
+  const open = openProp ?? uncontrolledOpen
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (!next) setActiveId(null)
+      setUncontrolledOpen(next)
+      onOpenChange?.(next)
+    },
+    [onOpenChange]
+  )
+
+  const matches = React.useCallback(
+    (itemValue: string, keywords: string[]) =>
+      filter(itemValue, inputValue, keywords),
+    [filter, inputValue]
+  )
+
+  const register = React.useCallback(
+    (itemValue: string, keywords: string[]) => {
+      setItems((current) => ({ ...current, [itemValue]: keywords }))
+      return () => {
+        setItems((current) => {
+          const next = { ...current }
+          delete next[itemValue]
+          return next
+        })
+      }
+    },
+    []
+  )
+
+  const itemId = React.useCallback(
+    (itemValue: string) => `${listId}-${encodeURIComponent(itemValue)}`,
+    [listId]
+  )
+
+  const select = React.useCallback(
+    (next: string) => {
+      onValueChange?.(next)
+      onInputValueChange(next)
+      setOpen(false)
+    },
+    [onInputValueChange, onValueChange, setOpen]
+  )
+
+  const visibleCount = Object.entries(items).filter(([itemValue, keywords]) =>
+    matches(itemValue, keywords)
+  ).length
+
+  const context: ComboboxContextValue = {
+    open,
+    setOpen,
+    value: value ?? null,
+    select,
+    inputValue,
+    setInputValue: onInputValueChange,
+    disabled,
+    matches,
+    register,
+    visibleCount,
+    listId,
+    activeId,
+    setActiveId,
+    itemId,
+    listRef,
+  }
+
+  return (
+    <ComboboxContext.Provider value={context}>
+      <PopoverPrimitive.Root open={open} onOpenChange={setOpen}>
+        {children}
+      </PopoverPrimitive.Root>
+    </ComboboxContext.Provider>
+  )
+}
+
+function ComboboxInput({
+  className,
+  showTrigger = true,
+  onKeyDown,
+  ...props
+}: React.ComponentProps<"input"> & { showTrigger?: boolean }) {
+  const combobox = useCombobox("ComboboxInput")
+  const { open, setOpen, setActiveId, listRef, select, disabled } = combobox
+
+  const move = (direction: 1 | -1) => {
+    const options = listRef.current?.querySelectorAll<HTMLElement>(
+      '[data-slot="combobox-item"]:not([hidden])'
+    )
+    if (!options?.length) return
+    const current = [...options].findIndex(
+      (option) => option.id === combobox.activeId
+    )
+    const next =
+      current === -1
+        ? direction === 1
+          ? 0
+          : options.length - 1
+        : (current + direction + options.length) % options.length
+    const option = options[next]
+    setActiveId(option.id)
+    option.scrollIntoView?.({ block: "nearest" })
+  }
+
+  return (
+    <PopoverPrimitive.Anchor asChild>
+      <InputGroup className={cn("w-auto", className)}>
+        <InputGroupInput
+          role="combobox"
+          autoComplete="off"
+          aria-expanded={open}
+          aria-controls={combobox.listId}
+          aria-autocomplete="list"
+          aria-activedescendant={
+            open ? (combobox.activeId ?? undefined) : undefined
+          }
+          disabled={disabled}
+          value={combobox.inputValue}
+          onChange={(event) => {
+            combobox.setInputValue(event.target.value)
+            setActiveId(null)
+            if (!open) setOpen(true)
+          }}
+          onClick={() => {
+            if (!open && !disabled) setOpen(true)
+          }}
+          onKeyDown={(event) => {
+            onKeyDown?.(event)
+            if (event.defaultPrevented) return
+            if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+              event.preventDefault()
+              if (!open) {
+                setOpen(true)
+                return
+              }
+              move(event.key === "ArrowDown" ? 1 : -1)
+              return
+            }
+            if (event.key === "Enter" && open && combobox.activeId) {
+              const option = listRef.current?.querySelector<HTMLElement>(
+                `#${CSS.escape(combobox.activeId)}`
+              )
+              if (option?.dataset.value) {
+                event.preventDefault()
+                select(option.dataset.value)
+              }
+              return
+            }
+            if (event.key === "Escape" && open) {
+              event.preventDefault()
+              setOpen(false)
+            }
+          }}
+          {...props}
+        />
+        {showTrigger ? (
+          <InputGroupAddon align="inline-end">
+            <PopoverPrimitive.Trigger asChild>
+              <InputGroupButton
+                size="icon-xs"
+                variant="ghost"
+                disabled={disabled}
+                tabIndex={-1}
+                data-slot="combobox-trigger"
+              >
+                <ChevronDownIcon className="text-muted-foreground" />
+              </InputGroupButton>
+            </PopoverPrimitive.Trigger>
+          </InputGroupAddon>
+        ) : null}
+      </InputGroup>
+    </PopoverPrimitive.Anchor>
+  )
+}
+
+function ComboboxContent({
+  className,
+  align = "start",
+  sideOffset = 6,
+  container,
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Content> & {
+  // Inside a modal Dialog, pass a host element within the dialog: the dialog's
+  // scroll lock only lets wheel events through for targets it contains, so a
+  // popup portalled to the body cannot scroll its own list.
+  container?: React.ComponentProps<typeof PopoverPrimitive.Portal>["container"]
+}) {
+  useCombobox("ComboboxContent")
+  return (
+    <PopoverPrimitive.Portal container={container}>
+      <PopoverPrimitive.Content
+        data-slot="combobox-content"
+        align={align}
+        sideOffset={sideOffset}
+        // The input keeps focus so typing continues to filter the list.
+        onOpenAutoFocus={(event) => event.preventDefault()}
+        onCloseAutoFocus={(event) => event.preventDefault()}
+        className={cn(
+          "z-50 max-h-(--radix-popover-content-available-height) w-(--radix-popover-trigger-width) origin-(--radix-popover-content-transform-origin) overflow-hidden rounded-lg bg-popover p-1 text-popover-foreground shadow-md ring-1 ring-foreground/10 duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2 data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
+          className
+        )}
+        {...props}
+      />
+    </PopoverPrimitive.Portal>
+  )
+}
+
+function ComboboxList({ className, ...props }: React.ComponentProps<"div">) {
+  const { listRef, listId } = useCombobox("ComboboxList")
+  return (
+    <div
+      ref={listRef}
+      id={listId}
+      role="listbox"
+      data-slot="combobox-list"
+      className={cn(
+        "max-h-60 scroll-py-1 overflow-y-auto overscroll-contain",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ComboboxGroup({ className, ...props }: React.ComponentProps<"div">) {
+  // Hidden wholesale when the query matches nothing, so its label does not
+  // caption an empty list.
+  const { visibleCount } = useCombobox("ComboboxGroup")
+  return (
+    <div
+      role="group"
+      data-slot="combobox-group"
+      hidden={visibleCount === 0}
+      className={cn(className)}
+      {...props}
+    />
+  )
+}
+
+function ComboboxLabel({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="combobox-label"
+      className={cn(
+        "px-1.5 py-1 text-xs font-medium text-muted-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ComboboxItem({
+  className,
+  children,
+  value,
+  keywords = [],
+  onClick,
+  ...props
+}: Omit<React.ComponentProps<"div">, "onSelect"> & {
+  value: string
+  keywords?: string[]
+}) {
+  const combobox = useCombobox("ComboboxItem")
+  const { register, matches, select, setActiveId, activeId, itemId } = combobox
+  const id = itemId(value)
+  // Keywords are stable per item in practice; joined so the effect is not
+  // re-run on every render by a fresh array literal.
+  const keywordKey = keywords.join("")
+
+  React.useEffect(
+    () => register(value, keywordKey ? keywordKey.split("") : []),
+    [register, value, keywordKey]
+  )
+
+  const visible = matches(value, keywords)
+  const selected = combobox.value === value
+
+  return (
+    <div
+      id={id}
+      role="option"
+      data-slot="combobox-item"
+      data-value={value}
+      data-highlighted={activeId === id ? "" : undefined}
+      aria-selected={selected}
+      hidden={!visible}
+      className={cn(
+        "relative flex w-full cursor-default items-center gap-1.5 rounded-md py-1 pr-8 pl-1.5 text-sm outline-hidden select-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-highlighted:**:text-accent-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      onPointerMove={() => setActiveId(id)}
+      // Selecting on pointer down keeps the input from losing focus first.
+      onPointerDown={(event) => event.preventDefault()}
+      onClick={(event) => {
+        onClick?.(event)
+        select(value)
+      }}
+      {...props}
+    >
+      {children}
+      {selected ? (
+        <span className="pointer-events-none absolute right-2 flex items-center justify-center">
+          <CheckIcon />
+        </span>
+      ) : null}
+    </div>
+  )
+}
+
+function ComboboxEmpty({ className, ...props }: React.ComponentProps<"div">) {
+  const { visibleCount } = useCombobox("ComboboxEmpty")
+  if (visibleCount > 0) return null
+  return (
+    <div
+      data-slot="combobox-empty"
+      className={cn(
+        "flex w-full justify-center py-2 text-center text-sm text-muted-foreground",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function ComboboxSeparator({
+  className,
+  ...props
+}: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="combobox-separator"
+      className={cn("-mx-1 my-1 h-px bg-border", className)}
+      {...props}
+    />
+  )
+}
+
+export {
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxGroup,
+  ComboboxLabel,
+  ComboboxItem,
+  ComboboxEmpty,
+  ComboboxSeparator,
+}
diff --git a/surfsense_local/frontend/src/components/ui/input-group.tsx b/surfsense_local/frontend/src/components/ui/input-group.tsx
new file mode 100644
index 0000000000..ebc4873cd3
--- /dev/null
+++ b/surfsense_local/frontend/src/components/ui/input-group.tsx
@@ -0,0 +1,136 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { cn } from "@/lib/utils"
+
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+
+function InputGroup({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="input-group"
+      role="group"
+      className={cn(
+        "group/input-group relative flex h-8 w-full min-w-0 items-center rounded-lg border border-input transition-colors outline-none in-data-[slot=combobox-content]:focus-within:border-inherit in-data-[slot=combobox-content]:focus-within:ring-0 has-disabled:bg-input/50 has-disabled:opacity-50 has-[[data-slot=input-group-control]:focus-visible]:border-ring/70 has-[[data-slot][aria-invalid=true]]:border-destructive has-[[data-slot][aria-invalid=true]]:ring-3 has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col dark:bg-input/30 dark:has-disabled:bg-input/80 dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40 has-[>[data-align=block-end]]:[&>input]:pt-3 has-[>[data-align=block-start]]:[&>input]:pb-3 has-[>[data-align=inline-end]]:[&>input]:pr-1.5 has-[>[data-align=inline-start]]:[&>input]:pl-1.5",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const inputGroupAddonVariants = cva(
+  "flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium text-muted-foreground select-none group-data-[disabled=true]/input-group:opacity-50 [&>kbd]:rounded-[calc(var(--radius)-5px)] [&>svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      align: {
+        "inline-start":
+          "order-first pl-2 has-[>button]:ml-[-0.3rem] has-[>kbd]:ml-[-0.15rem]",
+        "inline-end":
+          "order-last pr-2 has-[>button]:mr-[-0.3rem] has-[>kbd]:mr-[-0.15rem]",
+        "block-start":
+          "order-first w-full justify-start px-2.5 pt-2 group-has-[>input]/input-group:pt-2 [.border-b]:pb-2",
+        "block-end":
+          "order-last w-full justify-start px-2.5 pb-2 group-has-[>input]/input-group:pb-2 [.border-t]:pt-2",
+      },
+    },
+    defaultVariants: {
+      align: "inline-start",
+    },
+  }
+)
+
+function InputGroupAddon({
+  className,
+  align = "inline-start",
+  ...props
+}: React.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>) {
+  return (
+    <div
+      role="group"
+      data-slot="input-group-addon"
+      data-align={align}
+      className={cn(inputGroupAddonVariants({ align }), className)}
+      onClick={(e) => {
+        if ((e.target as HTMLElement).closest("button")) {
+          return
+        }
+        e.currentTarget.parentElement?.querySelector("input")?.focus()
+      }}
+      {...props}
+    />
+  )
+}
+
+const inputGroupButtonVariants = cva(
+  "flex items-center gap-2 text-sm shadow-none",
+  {
+    variants: {
+      size: {
+        xs: "h-6 gap-1 rounded-[calc(var(--radius)-3px)] px-1.5 [&>svg:not([class*='size-'])]:size-3.5",
+        sm: "",
+        "icon-xs":
+          "size-6 rounded-[calc(var(--radius)-3px)] p-0 has-[>svg]:p-0",
+        "icon-sm": "size-8 p-0 has-[>svg]:p-0",
+      },
+    },
+    defaultVariants: {
+      size: "xs",
+    },
+  }
+)
+
+function InputGroupButton({
+  className,
+  type = "button",
+  variant = "ghost",
+  size = "xs",
+  ...props
+}: Omit<React.ComponentProps<typeof Button>, "size"> &
+  VariantProps<typeof inputGroupButtonVariants>) {
+  return (
+    <Button
+      type={type}
+      data-size={size}
+      variant={variant}
+      className={cn(inputGroupButtonVariants({ size }), className)}
+      {...props}
+    />
+  )
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<"span">) {
+  return (
+    <span
+      className={cn(
+        "flex items-center gap-2 text-sm text-muted-foreground [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function InputGroupInput({
+  className,
+  ...props
+}: React.ComponentProps<"input">) {
+  return (
+    <Input
+      data-slot="input-group-control"
+      className={cn(
+        "flex-1 rounded-none border-0 bg-transparent shadow-none ring-0 focus-visible:ring-0 disabled:bg-transparent aria-invalid:ring-0 dark:bg-transparent dark:disabled:bg-transparent",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupText,
+  InputGroupInput,
+}
diff --git a/surfsense_local/frontend/src/features/model-selection/connection-form.tsx b/surfsense_local/frontend/src/features/model-selection/connection-form.tsx
index 1dfa89437b..8df2d7fa57 100644
--- a/surfsense_local/frontend/src/features/model-selection/connection-form.tsx
+++ b/surfsense_local/frontend/src/features/model-selection/connection-form.tsx
@@ -10,6 +10,16 @@ import {
   DialogHeader,
   DialogTitle,
 } from "@/components/ui/dialog"
+import {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxInput,
+  ComboboxItem,
+  ComboboxLabel,
+  ComboboxList,
+} from "@/components/ui/combobox"
 import { Field, FieldLabel } from "@/components/ui/field"
 import { Input } from "@/components/ui/input"
 import { Spinner } from "@/components/ui/spinner"
@@ -22,6 +32,29 @@ import {
   type ConnectionWrite,
 } from "./api"
 
+const COMMON_BASE_URLS = [
+  { name: "OpenAI", url: "https://api.openai.com/v1" },
+  { name: "OpenRouter", url: "https://openrouter.ai/api/v1" },
+  { name: "Together AI", url: "https://api.together.xyz/v1" },
+  { name: "Groq", url: "https://api.groq.com/openai/v1" },
+  { name: "DeepSeek", url: "https://api.deepseek.com/v1" },
+  { name: "Mistral", url: "https://api.mistral.ai/v1" },
+  { name: "Fireworks", url: "https://api.fireworks.ai/inference/v1" },
+  { name: "xAI", url: "https://api.x.ai/v1" },
+  { name: "Cerebras", url: "https://api.cerebras.ai/v1" },
+  {
+    name: "Google Gemini",
+    url: "https://generativelanguage.googleapis.com/v1beta/openai",
+  },
+  { name: "Ollama (local)", url: "http://localhost:11434/v1" },
+  { name: "LM Studio (local)", url: "http://localhost:1234/v1" },
+  { name: "vLLM (local)", url: "http://localhost:8000/v1" },
+] as const
+
+function presetFor(url: string) {
+  return COMMON_BASE_URLS.find((entry) => entry.url === url)
+}
+
 function messageFrom(error: unknown) {
   return error instanceof Error ? error.message : "Could not save connection"
 }
@@ -46,6 +79,10 @@ export function ConnectionForm({
     null
   )
   const [canSaveAnyway, setCanSaveAnyway] = useState(false)
+  // Hosts the combobox popup inside the dialog so the dialog's scroll lock
+  // lets the list scroll. Absolute, so it adds no height and the dialog, which
+  // is centred by transform, does not shift when the popup opens.
+  const [popupHost, setPopupHost] = useState<HTMLDivElement | null>(null)
 
   const save = async (allowUnverified: boolean) => {
     setBusy(true)
@@ -88,6 +125,7 @@ export function ConnectionForm({
           </DialogDescription>
         </DialogHeader>
         <div className="space-y-3">
+          <div ref={setPopupHost} className="absolute" />
           <Input
             value={label}
             onChange={(event) => setLabel(event.target.value)}
@@ -95,13 +133,43 @@ export function ConnectionForm({
             aria-label="Connection label"
             disabled={busy}
           />
-          <Input
+          <Combobox
             value={baseUrl}
-            onChange={(event) => setBaseUrl(event.target.value)}
-            placeholder="https://models.example.com/v1"
-            aria-label="Base URL"
+            onValueChange={(url) => {
+              const preset = presetFor(url)
+              if (preset && !label.trim()) setLabel(preset.name)
+            }}
+            inputValue={baseUrl}
+            onInputValueChange={setBaseUrl}
             disabled={busy}
-          />
+          >
+            <ComboboxInput
+              placeholder="https://models.example.com/v1"
+              aria-label="Base URL"
+            />
+            <ComboboxContent container={popupHost}>
+              <ComboboxEmpty>No items found</ComboboxEmpty>
+              <ComboboxList>
+                <ComboboxGroup>
+                  <ComboboxLabel>Common endpoints</ComboboxLabel>
+                  {COMMON_BASE_URLS.map((entry) => (
+                    <ComboboxItem
+                      key={entry.url}
+                      value={entry.url}
+                      keywords={[entry.name]}
+                    >
+                      <span className="min-w-0 flex-1 truncate">
+                        {entry.name}
+                        <span className="ml-1.5 text-muted-foreground">
+                          {entry.url}
+                        </span>
+                      </span>
+                    </ComboboxItem>
+                  ))}
+                </ComboboxGroup>
+              </ComboboxList>
+            </ComboboxContent>
+          </Combobox>
           <Input
             type="password"
             autoComplete="off"

From 29859e06b409b63e2ba20563734eccd2249a8087 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 15 Sep 2026 03:32:33 +0530
Subject: [PATCH 2/9] fix(local): use the shared Checkbox in network and update
 settings

---
 .../frontend/src/features/egress/network-settings.tsx    | 7 +++----
 .../frontend/src/features/updates/update-settings.tsx    | 9 ++++-----
 2 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/surfsense_local/frontend/src/features/egress/network-settings.tsx b/surfsense_local/frontend/src/features/egress/network-settings.tsx
index 24dadfbd8e..ceedfa72f7 100644
--- a/surfsense_local/frontend/src/features/egress/network-settings.tsx
+++ b/surfsense_local/frontend/src/features/egress/network-settings.tsx
@@ -2,6 +2,7 @@ import { useEffect, useState } from "react"
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
 
 import { RelativeTime } from "@/components/relative-time"
+import { Checkbox } from "@/components/ui/checkbox"
 import { Skeleton } from "@/components/ui/skeleton"
 import { SettingsSection } from "@/features/settings/settings-section"
 import type { UpdatePrefs } from "@/lib/api"
@@ -38,11 +39,9 @@ function DestinationRow({
         </p>
       </div>
       <label className="flex shrink-0 items-center gap-2 text-sm">
-        <input
-          type="checkbox"
-          className="size-4 accent-primary"
+        <Checkbox
           checked={enabled}
-          onChange={(event) => onChange(event.target.checked)}
+          onCheckedChange={(checked) => onChange(checked === true)}
         />
         <span className="sr-only">Allow {label}</span>
       </label>
diff --git a/surfsense_local/frontend/src/features/updates/update-settings.tsx b/surfsense_local/frontend/src/features/updates/update-settings.tsx
index ae9abde08c..8c9c77d544 100644
--- a/surfsense_local/frontend/src/features/updates/update-settings.tsx
+++ b/surfsense_local/frontend/src/features/updates/update-settings.tsx
@@ -1,6 +1,7 @@
 import { useEffect, useState } from "react"
 
 import { Button } from "@/components/ui/button"
+import { Checkbox } from "@/components/ui/checkbox"
 import { DownloadCircle02Icon } from "@/components/ui/icons"
 import {
   Tooltip,
@@ -73,12 +74,10 @@ export function UpdateSettings() {
           turn this on, SurfSense never checks on its own.
         </p>
         <label className="mt-2 flex items-center gap-2 text-sm">
-          <input
-            type="checkbox"
-            className="size-4 accent-primary"
+          <Checkbox
             checked={automatic}
-            onChange={(event) => {
-              const next = event.target.checked
+            onCheckedChange={(checked) => {
+              const next = checked === true
               setAutomatic(next)
               void updates.setAutomatic(next)
             }}

From e050964bf7fb60787666be87ae55135220966478 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 15 Sep 2026 03:40:09 +0530
Subject: [PATCH 3/9] feat(local): require Cmd/Ctrl+Shift+D to toggle the theme

---
 surfsense_local/frontend/src/components/theme-provider.tsx  | 5 ++++-
 .../frontend/src/features/updates/update-settings.test.tsx  | 6 ++++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/surfsense_local/frontend/src/components/theme-provider.tsx b/surfsense_local/frontend/src/components/theme-provider.tsx
index 6121ac9609..790944206b 100644
--- a/surfsense_local/frontend/src/components/theme-provider.tsx
+++ b/surfsense_local/frontend/src/components/theme-provider.tsx
@@ -159,7 +159,8 @@ export function ThemeProvider({
         return
       }
 
-      if (event.metaKey || event.ctrlKey || event.altKey) {
+      // Cmd/Ctrl+Shift+D, so a bare "d" while typing never flips the theme.
+      if (!(event.metaKey || event.ctrlKey) || !event.shiftKey || event.altKey) {
         return
       }
 
@@ -171,6 +172,8 @@ export function ThemeProvider({
         return
       }
 
+      event.preventDefault()
+
       setThemeState((currentTheme) => {
         const nextTheme =
           currentTheme === "dark"
diff --git a/surfsense_local/frontend/src/features/updates/update-settings.test.tsx b/surfsense_local/frontend/src/features/updates/update-settings.test.tsx
index 4521e816b8..d7385579ee 100644
--- a/surfsense_local/frontend/src/features/updates/update-settings.test.tsx
+++ b/surfsense_local/frontend/src/features/updates/update-settings.test.tsx
@@ -63,10 +63,12 @@ describe("UpdateSettings", () => {
     const toggle = await screen.findByRole("checkbox", {
       name: "Check for updates automatically",
     })
-    expect(toggle).toHaveProperty("checked", false)
+    expect(toggle.getAttribute("aria-checked")).toBe("false")
     await user.click(toggle)
 
-    await waitFor(() => expect(toggle).toHaveProperty("checked", true))
+    await waitFor(() =>
+      expect(toggle.getAttribute("aria-checked")).toBe("true")
+    )
     expect(bridge.calls).toEqual(["automatic:true"])
   })
 

From 964ca3f242ead6298539fa765793bdca4fb4d582 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 15 Sep 2026 04:00:05 +0530
Subject: [PATCH 4/9] feat(local): add a Plugins sidebar button and xl/2xl
 Button sizes

---
 .../frontend/src/components/ui/button.tsx     |  5 ++
 .../frontend/src/components/ui/icons.tsx      |  2 +
 .../src/features/chat/thread-list.test.tsx    | 48 ++++++++++++++-
 .../src/features/chat/thread-list.tsx         | 58 +++++++++++++++----
 .../src/features/dashboard/dashboard-page.tsx | 11 ++++
 .../features/workspaces/workspace-rail.tsx    |  4 +-
 6 files changed, 113 insertions(+), 15 deletions(-)

diff --git a/surfsense_local/frontend/src/components/ui/button.tsx b/surfsense_local/frontend/src/components/ui/button.tsx
index 2f618fb866..202c3baec7 100644
--- a/surfsense_local/frontend/src/components/ui/button.tsx
+++ b/surfsense_local/frontend/src/components/ui/button.tsx
@@ -26,12 +26,17 @@ const buttonVariants = cva(
         xs: "h-6 gap-1 rounded-[min(var(--radius-md),10px)] px-2 text-xs in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3",
         sm: "h-7 gap-1 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] in-data-[slot=button-group]:rounded-lg has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
         lg: "h-9 gap-1.5 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
+        xl: "h-10 gap-2 px-3 text-base has-data-[icon=inline-end]:pr-2.5 has-data-[icon=inline-start]:pl-2.5 [&_svg:not([class*='size-'])]:size-4.5",
+        "2xl":
+          "h-11 gap-2 px-3.5 text-lg has-data-[icon=inline-end]:pr-3 has-data-[icon=inline-start]:pl-3 [&_svg:not([class*='size-'])]:size-5",
         icon: "size-8",
         "icon-xs":
           "size-6 rounded-[min(var(--radius-md),10px)] in-data-[slot=button-group]:rounded-lg [&_svg:not([class*='size-'])]:size-3",
         "icon-sm":
           "size-7 rounded-[min(var(--radius-md),12px)] in-data-[slot=button-group]:rounded-lg",
         "icon-lg": "size-9",
+        "icon-xl": "size-10 [&_svg:not([class*='size-'])]:size-4.5",
+        "icon-2xl": "size-11 [&_svg:not([class*='size-'])]:size-5",
       },
     },
     defaultVariants: {
diff --git a/surfsense_local/frontend/src/components/ui/icons.tsx b/surfsense_local/frontend/src/components/ui/icons.tsx
index 8d4b670c10..cbdf2adf16 100644
--- a/surfsense_local/frontend/src/components/ui/icons.tsx
+++ b/surfsense_local/frontend/src/components/ui/icons.tsx
@@ -53,6 +53,7 @@ import {
   SquareDashedMousePointerIcon as SquareDashedMousePointerIconData,
   StopCircleIcon,
   Sun03Icon as Sun03IconData,
+  UnplugIcon as UnplugIconData,
   Upload01Icon as Upload01IconData,
   ComputerIcon as ComputerIconData,
   ViewIcon as ViewIconData,
@@ -136,6 +137,7 @@ export const Settings2Icon = createIcon(Settings02Icon)
 export const Shapes01Icon = createIcon(Shapes01IconData)
 export const SparklesIcon = createIcon(SparklesIconData)
 export const SunIcon = createIcon(Sun03IconData)
+export const UnplugIcon = createIcon(UnplugIconData)
 export const Upload01Icon = createIcon(Upload01IconData)
 export const ComputerIcon = createIcon(ComputerIconData)
 export const SquareDashedMousePointerIcon = createIcon(
diff --git a/surfsense_local/frontend/src/features/chat/thread-list.test.tsx b/surfsense_local/frontend/src/features/chat/thread-list.test.tsx
index c7fd4c64ae..de3bcd9df1 100644
--- a/surfsense_local/frontend/src/features/chat/thread-list.test.tsx
+++ b/surfsense_local/frontend/src/features/chat/thread-list.test.tsx
@@ -4,7 +4,11 @@ import { afterEach, describe, expect, it, vi } from "vitest"
 
 import { render } from "@/test-utils"
 
-import { ThreadList } from "./thread-list"
+import { ThreadList, type SidebarNavAction } from "./thread-list"
+
+function UnplugIcon(props: { className?: string }) {
+  return <svg data-testid="unplug-icon" {...props} />
+}
 
 afterEach(cleanup)
 
@@ -89,7 +93,7 @@ describe("ThreadList", () => {
     expect(chatButton.className).toContain("text-foreground")
     expect(chatButton.className).toContain("group-hover:bg-muted")
     expect(chatButton.className).toContain("dark:group-hover:bg-muted/50")
-    expect(chatButton.className).toContain("active:!translate-y-0")
+    expect(chatButton.className).toContain("active:translate-y-0!")
     expect(actionsButton.className).toContain("size-6")
     expect(actionsButton.className).toContain("active:translate-y-px")
     expect(titleContainer?.className).toContain("min-w-0")
@@ -134,4 +138,44 @@ describe("ThreadList", () => {
     ).toContain("select-none")
     expect(screen.queryByText("No chats yet")).toBeNull()
   })
+
+  it("renders each extra action the same way as New chat", async () => {
+    const onPlugins = vi.fn()
+    const user = userEvent.setup()
+    const actions: SidebarNavAction[] = [
+      {
+        key: "plugins",
+        label: "Plugins",
+        icon: UnplugIcon,
+        onClick: onPlugins,
+      },
+    ]
+
+    render(
+      <ThreadList
+        threads={[]}
+        activeThreadId={null}
+        autoNamingThreadId={null}
+        animatingTitleThreadId={null}
+        isLoading={false}
+        onNewChat={vi.fn()}
+        onSelect={vi.fn()}
+        onRename={vi.fn(async () => true)}
+        onDelete={vi.fn(async () => undefined)}
+        onTitleAnimationComplete={vi.fn()}
+        actions={actions}
+      />
+    )
+
+    const newChat = screen.getByRole("button", { name: "New chat" })
+    const plugins = screen.getByRole("button", { name: "Plugins" })
+    expect(plugins.getAttribute("data-variant")).toBe(
+      newChat.getAttribute("data-variant")
+    )
+    expect(plugins.className).toBe(newChat.className)
+    expect(plugins.querySelector("[data-testid='unplug-icon']")).toBeTruthy()
+
+    await user.click(plugins)
+    expect(onPlugins).toHaveBeenCalledOnce()
+  })
 })
diff --git a/surfsense_local/frontend/src/features/chat/thread-list.tsx b/surfsense_local/frontend/src/features/chat/thread-list.tsx
index df66e38f55..93f1b30aac 100644
--- a/surfsense_local/frontend/src/features/chat/thread-list.tsx
+++ b/surfsense_local/frontend/src/features/chat/thread-list.tsx
@@ -1,4 +1,9 @@
-import { useRef, useState, type FormEvent } from "react"
+import {
+  useRef,
+  useState,
+  type ComponentType,
+  type SubmitEvent,
+} from "react"
 
 import {
   ChevronRightIcon,
@@ -32,6 +37,32 @@ import { cn } from "@/lib/utils"
 
 import type { ChatThread } from "./api"
 
+// A row rendered below "New chat" with the same look. Add an entry here (or
+// pass one through `actions`) rather than hand-rolling another Button.
+export type SidebarNavAction = {
+  key: string
+  label: string
+  icon: ComponentType<{ className?: string }>
+  onClick: () => void
+}
+
+function SidebarNavButton({
+  label,
+  icon: Icon,
+  onClick,
+}: Omit<SidebarNavAction, "key">) {
+  return (
+    <Button
+      variant="ghost"
+      className="w-full justify-start px-2"
+      onClick={onClick}
+    >
+      <Icon />
+      {label}
+    </Button>
+  )
+}
+
 export function RenameChatDialog({
   thread,
   onClose,
@@ -45,7 +76,7 @@ export function RenameChatDialog({
   const [title, setTitle] = useState(thread.title || "New chat")
   const [isSubmitting, setIsSubmitting] = useState(false)
 
-  const submit = async (event: FormEvent) => {
+  const submit = async (event: SubmitEvent) => {
     event.preventDefault()
     const normalized = title.trim()
     if (!normalized) return
@@ -107,6 +138,7 @@ export function ThreadList({
   onRename,
   onDelete,
   onTitleAnimationComplete,
+  actions = [],
 }: {
   threads: ChatThread[]
   activeThreadId: number | null
@@ -118,6 +150,8 @@ export function ThreadList({
   onRename: (id: number, title: string) => Promise<boolean>
   onDelete: (id: number) => Promise<void>
   onTitleAnimationComplete: () => void
+  // Extra rows below "New chat", same look. Append here to add one.
+  actions?: SidebarNavAction[]
 }) {
   const [openDropdownId, setOpenDropdownId] = useState<number | null>(null)
   const [renaming, setRenaming] = useState<ChatThread | null>(null)
@@ -129,14 +163,16 @@ export function ThreadList({
         <h2 className="truncate px-1 font-heading text-lg font-medium text-foreground select-none">
           SurfSense
         </h2>
-        <Button
-          variant="ghost"
-          className="w-full justify-start px-2"
-          onClick={onNewChat}
-        >
-          <PencilEdit02Icon />
-          New chat
-        </Button>
+        <div className="flex flex-col">
+          <SidebarNavButton
+            label="New chat"
+            icon={PencilEdit02Icon}
+            onClick={onNewChat}
+          />
+          {actions.map(({ key, ...action }) => (
+            <SidebarNavButton key={key} {...action} />
+          ))}
+        </div>
       </header>
       <ScrollShadow
         className="min-h-0 min-w-0 flex-1"
@@ -177,7 +213,7 @@ export function ThreadList({
                 <Button
                   variant="ghost"
                   className={cn(
-                    "h-8 w-full min-w-0 justify-start overflow-hidden px-2 py-1.5 text-sm font-normal group-hover:bg-muted active:!translate-y-0 dark:group-hover:bg-muted/50",
+                    "h-8 w-full min-w-0 justify-start overflow-hidden px-2 py-1.5 text-sm font-normal group-hover:bg-muted active:translate-y-0! dark:group-hover:bg-muted/50",
                     selected &&
                       "bg-sidebar-accent text-foreground group-hover:text-foreground hover:text-foreground",
                     openDropdownId === thread.id && "bg-muted dark:bg-muted/50"
diff --git a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
index ce44c4d908..e6ad2d540a 100644
--- a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
+++ b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
@@ -1,9 +1,11 @@
 import { useEffect, useState } from "react"
+import { toast } from "sonner"
 import {
   CircleAlertIcon,
   LayoutGridIcon,
   PlusIcon,
   SidebarRightIcon,
+  UnplugIcon,
   XIcon,
 } from "@/components/ui/icons"
 
@@ -148,6 +150,15 @@ function WorkspaceDashboard({
               await chat.removeThread(threadId)
             }}
             onTitleAnimationComplete={chat.finishTitleAnimation}
+            actions={[
+              {
+                key: "plugins",
+                label: "Plugins",
+                icon: UnplugIcon,
+                // TODO: open the plugins panel once it exists.
+                onClick: () => toast.info("Plugins are coming soon"),
+              },
+            ]}
           />
         </div>
         <div className="flex min-h-0 min-w-[520px] flex-1 flex-col">
diff --git a/surfsense_local/frontend/src/features/workspaces/workspace-rail.tsx b/surfsense_local/frontend/src/features/workspaces/workspace-rail.tsx
index 7a434cb84f..a8b0598dd9 100644
--- a/surfsense_local/frontend/src/features/workspaces/workspace-rail.tsx
+++ b/surfsense_local/frontend/src/features/workspaces/workspace-rail.tsx
@@ -1,4 +1,4 @@
-import { useRef, useState, type FormEvent } from "react"
+import { useRef, useState, type SubmitEvent } from "react"
 import {
   PencilIcon,
   PlusIcon,
@@ -77,7 +77,7 @@ function WorkspaceNameDialog({
   const [name, setName] = useState(initialName)
   const [isSubmitting, setIsSubmitting] = useState(false)
 
-  const submit = async (event: FormEvent) => {
+  const submit = async (event: SubmitEvent) => {
     event.preventDefault()
     const normalized = name.trim()
     if (!normalized) {

From da6ae9aa944a824e38a554ecaca464d7a41e4f45 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 15 Sep 2026 04:07:52 +0530
Subject: [PATCH 5/9] feat(local): add a "Coming soon" badge to the sidebar
 Plugins button

---
 .../src/features/chat/thread-list.test.tsx    |  37 ++++
 .../src/features/chat/thread-list.tsx         | 180 +++++++++---------
 .../src/features/dashboard/dashboard-page.tsx |   1 +
 .../src/features/egress/network-settings.tsx  |   6 +-
 4 files changed, 135 insertions(+), 89 deletions(-)

diff --git a/surfsense_local/frontend/src/features/chat/thread-list.test.tsx b/surfsense_local/frontend/src/features/chat/thread-list.test.tsx
index de3bcd9df1..9fc59d8cca 100644
--- a/surfsense_local/frontend/src/features/chat/thread-list.test.tsx
+++ b/surfsense_local/frontend/src/features/chat/thread-list.test.tsx
@@ -178,4 +178,41 @@ describe("ThreadList", () => {
     await user.click(plugins)
     expect(onPlugins).toHaveBeenCalledOnce()
   })
+
+  it("shows an action's badge next to its label", () => {
+    const actions: SidebarNavAction[] = [
+      {
+        key: "plugins",
+        label: "Plugins",
+        icon: UnplugIcon,
+        badge: "Coming soon",
+        onClick: vi.fn(),
+      },
+    ]
+
+    render(
+      <ThreadList
+        threads={[]}
+        activeThreadId={null}
+        autoNamingThreadId={null}
+        animatingTitleThreadId={null}
+        isLoading={false}
+        onNewChat={vi.fn()}
+        onSelect={vi.fn()}
+        onRename={vi.fn(async () => true)}
+        onDelete={vi.fn(async () => undefined)}
+        onTitleAnimationComplete={vi.fn()}
+        actions={actions}
+      />
+    )
+
+    const badge = screen.getByText("Coming soon")
+    expect(badge.closest('[data-slot="badge"]')).toBeTruthy()
+    expect(
+      screen.getByRole("button", { name: /^Plugins/ }).contains(badge)
+    ).toBe(true)
+    expect(
+      screen.getByRole("button", { name: "New chat" }).textContent
+    ).not.toContain("Coming soon")
+  })
 })
diff --git a/surfsense_local/frontend/src/features/chat/thread-list.tsx b/surfsense_local/frontend/src/features/chat/thread-list.tsx
index 93f1b30aac..7c3c7713a4 100644
--- a/surfsense_local/frontend/src/features/chat/thread-list.tsx
+++ b/surfsense_local/frontend/src/features/chat/thread-list.tsx
@@ -1,9 +1,4 @@
-import {
-  useRef,
-  useState,
-  type ComponentType,
-  type SubmitEvent,
-} from "react"
+import { useRef, useState, type ComponentType, type SubmitEvent } from "react"
 
 import {
   ChevronRightIcon,
@@ -13,6 +8,7 @@ import {
   Trash2Icon,
 } from "@/components/ui/icons"
 
+import { Badge } from "@/components/ui/badge"
 import { Button } from "@/components/ui/button"
 import {
   DropdownMenu,
@@ -44,12 +40,14 @@ export type SidebarNavAction = {
   label: string
   icon: ComponentType<{ className?: string }>
   onClick: () => void
+  badge?: string
 }
 
 function SidebarNavButton({
   label,
   icon: Icon,
   onClick,
+  badge,
 }: Omit<SidebarNavAction, "key">) {
   return (
     <Button
@@ -58,7 +56,12 @@ function SidebarNavButton({
       onClick={onClick}
     >
       <Icon />
-      {label}
+      <span className="text-left">{label}</span>
+      {badge ? (
+        <Badge variant="secondary" className="ml-2 rounded-md">
+          {badge}
+        </Badge>
+      ) : null}
     </Button>
   )
 }
@@ -182,7 +185,7 @@ export function ThreadList({
         <div className="flex w-full max-w-full min-w-0 flex-col gap-1">
           <button
             type="button"
-            className="group flex min-h-7 items-center gap-1 px-2 text-xs font-semibold text-muted-foreground transition-colors select-none hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            className="group flex min-h-7 items-center gap-1 px-2 text-xs font-semibold text-muted-foreground transition-colors select-none hover:text-accent-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none"
             aria-expanded={recentsOpen}
             onClick={() => setRecentsOpen((open) => !open)}
           >
@@ -203,89 +206,90 @@ export function ThreadList({
                 </p>
               ) : null}
               {threads.map((thread) => {
-            const selected = thread.id === activeThreadId
-            const title = thread.title || "New chat"
-            return (
-              <div
-                key={thread.id}
-                className="group relative w-full min-w-0 overflow-hidden rounded-md"
-              >
-                <Button
-                  variant="ghost"
-                  className={cn(
-                    "h-8 w-full min-w-0 justify-start overflow-hidden px-2 py-1.5 text-sm font-normal group-hover:bg-muted active:translate-y-0! dark:group-hover:bg-muted/50",
-                    selected &&
-                      "bg-sidebar-accent text-foreground group-hover:text-foreground hover:text-foreground",
-                    openDropdownId === thread.id && "bg-muted dark:bg-muted/50"
-                  )}
-                  aria-current={selected ? "page" : undefined}
-                  onClick={() => onSelect(thread.id)}
-                >
-                  <span
-                    className={cn(
-                      "sidebar-row-title-fade sidebar-row-title-fade-focus-within min-w-0 flex-1 overflow-hidden text-left whitespace-nowrap",
-                      openDropdownId === thread.id &&
-                        "sidebar-row-title-fade-actions"
-                    )}
+                const selected = thread.id === activeThreadId
+                const title = thread.title || "New chat"
+                return (
+                  <div
+                    key={thread.id}
+                    className="group relative w-full min-w-0 overflow-hidden rounded-md"
                   >
-                    <TypewriterText
-                      text={title}
-                      animate={thread.id === animatingTitleThreadId}
-                      onComplete={onTitleAnimationComplete}
-                    />
-                  </span>
-                </Button>
-                <div className="absolute inset-y-0 right-0 flex items-center rounded-r-md py-1 pr-1">
-                  <DropdownMenu
-                    open={openDropdownId === thread.id}
-                    onOpenChange={(open) =>
-                      setOpenDropdownId(open ? thread.id : null)
-                    }
-                  >
-                    <DropdownMenuTrigger asChild>
-                      <Button
-                        variant="ghost"
-                        size="icon-sm"
-                        className="size-6 opacity-0 group-focus-within:opacity-100 group-hover:opacity-100 hover:bg-transparent active:translate-y-px data-[state=open]:bg-accent data-[state=open]:opacity-100"
-                        aria-label={`Actions for ${title}`}
-                      >
-                        <EllipsisIcon />
-                      </Button>
-                    </DropdownMenuTrigger>
-                    <DropdownMenuContent
-                      align="end"
-                      sideOffset={8}
-                      className="w-36"
-                      onCloseAutoFocus={(event) => event.preventDefault()}
+                    <Button
+                      variant="ghost"
+                      className={cn(
+                        "h-8 w-full min-w-0 justify-start overflow-hidden px-2 py-1.5 text-sm font-normal group-hover:bg-muted active:translate-y-0! dark:group-hover:bg-muted/50",
+                        selected &&
+                          "bg-sidebar-accent text-foreground group-hover:text-foreground hover:text-foreground",
+                        openDropdownId === thread.id &&
+                          "bg-muted dark:bg-muted/50"
+                      )}
+                      aria-current={selected ? "page" : undefined}
+                      onClick={() => onSelect(thread.id)}
                     >
-                      <DropdownMenuGroup>
-                        <DropdownMenuItem
-                          disabled={thread.id === autoNamingThreadId}
-                          onSelect={() => {
-                            setOpenDropdownId(null)
-                            setRenaming(thread)
-                          }}
-                        >
-                          <PencilIcon />
-                          Rename
-                        </DropdownMenuItem>
-                        <DropdownMenuItem
-                          variant="destructive"
-                          onSelect={() => {
-                            setOpenDropdownId(null)
-                            void onDelete(thread.id)
-                          }}
+                      <span
+                        className={cn(
+                          "sidebar-row-title-fade sidebar-row-title-fade-focus-within min-w-0 flex-1 overflow-hidden text-left whitespace-nowrap",
+                          openDropdownId === thread.id &&
+                            "sidebar-row-title-fade-actions"
+                        )}
+                      >
+                        <TypewriterText
+                          text={title}
+                          animate={thread.id === animatingTitleThreadId}
+                          onComplete={onTitleAnimationComplete}
+                        />
+                      </span>
+                    </Button>
+                    <div className="absolute inset-y-0 right-0 flex items-center rounded-r-md py-1 pr-1">
+                      <DropdownMenu
+                        open={openDropdownId === thread.id}
+                        onOpenChange={(open) =>
+                          setOpenDropdownId(open ? thread.id : null)
+                        }
+                      >
+                        <DropdownMenuTrigger asChild>
+                          <Button
+                            variant="ghost"
+                            size="icon-sm"
+                            className="size-6 opacity-0 group-focus-within:opacity-100 group-hover:opacity-100 hover:bg-transparent active:translate-y-px data-[state=open]:bg-accent data-[state=open]:opacity-100"
+                            aria-label={`Actions for ${title}`}
+                          >
+                            <EllipsisIcon />
+                          </Button>
+                        </DropdownMenuTrigger>
+                        <DropdownMenuContent
+                          align="end"
+                          sideOffset={8}
+                          className="w-36"
+                          onCloseAutoFocus={(event) => event.preventDefault()}
                         >
-                          <Trash2Icon />
-                          Delete chat
-                        </DropdownMenuItem>
-                      </DropdownMenuGroup>
-                    </DropdownMenuContent>
-                  </DropdownMenu>
-                </div>
-              </div>
-            )
-          })}
+                          <DropdownMenuGroup>
+                            <DropdownMenuItem
+                              disabled={thread.id === autoNamingThreadId}
+                              onSelect={() => {
+                                setOpenDropdownId(null)
+                                setRenaming(thread)
+                              }}
+                            >
+                              <PencilIcon />
+                              Rename
+                            </DropdownMenuItem>
+                            <DropdownMenuItem
+                              variant="destructive"
+                              onSelect={() => {
+                                setOpenDropdownId(null)
+                                void onDelete(thread.id)
+                              }}
+                            >
+                              <Trash2Icon />
+                              Delete chat
+                            </DropdownMenuItem>
+                          </DropdownMenuGroup>
+                        </DropdownMenuContent>
+                      </DropdownMenu>
+                    </div>
+                  </div>
+                )
+              })}
             </>
           ) : null}
         </div>
diff --git a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
index e6ad2d540a..84c1cab641 100644
--- a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
+++ b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
@@ -155,6 +155,7 @@ function WorkspaceDashboard({
                 key: "plugins",
                 label: "Plugins",
                 icon: UnplugIcon,
+                badge: "Coming soon",
                 // TODO: open the plugins panel once it exists.
                 onClick: () => toast.info("Plugins are coming soon"),
               },
diff --git a/surfsense_local/frontend/src/features/egress/network-settings.tsx b/surfsense_local/frontend/src/features/egress/network-settings.tsx
index ceedfa72f7..9904d6f8d5 100644
--- a/surfsense_local/frontend/src/features/egress/network-settings.tsx
+++ b/surfsense_local/frontend/src/features/egress/network-settings.tsx
@@ -3,6 +3,7 @@ import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"
 
 import { RelativeTime } from "@/components/relative-time"
 import { Checkbox } from "@/components/ui/checkbox"
+import { DotIcon } from "@/components/ui/icons"
 import { Skeleton } from "@/components/ui/skeleton"
 import { SettingsSection } from "@/features/settings/settings-section"
 import type { UpdatePrefs } from "@/lib/api"
@@ -33,7 +34,10 @@ function DestinationRow({
         <p className="text-sm font-medium">{label}</p>
         <p className="truncate text-xs text-muted-foreground">
           {host}
-          <span aria-hidden> · </span>
+          <DotIcon
+            aria-hidden="true"
+            className="mx-1 inline size-3 align-middle"
+          />
           Last call:{" "}
           {lastCallAt ? <RelativeTime date={new Date(lastCallAt)} /> : "never"}
         </p>

From 45eb69927441eb22c878ead25efbe29ffcca6f6f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 15 Sep 2026 04:59:51 +0530
Subject: [PATCH 6/9] fix(local): enable rich toast colors and drop raw errors
 from artifact-failure toasts

---
 .../backend/modules/artifacts/router.py       |  12 +-
 .../backend/modules/artifacts/service.py      |  22 ++
 .../integration/artifacts/test_routes.py      |  48 ++-
 .../frontend/src/components/ui/sonner.tsx     |   4 +
 .../src/features/chat/thread-list.tsx         |   2 +-
 .../src/features/dashboard/dashboard-page.tsx |   7 +-
 .../features/sources/source-upload.test.tsx   | 137 ++++++--
 .../src/features/sources/sources-panel.tsx    | 296 ++++++++++--------
 .../frontend/src/features/studio/api.ts       |  10 +
 .../features/studio/artifact-list.test.tsx    |  91 +++++-
 .../src/features/studio/artifact-list.tsx     | 211 +++++++------
 .../src/features/studio/studio-panel.test.tsx |   1 +
 .../src/features/studio/use-studio.test.ts    | 148 +++++++++
 .../src/features/studio/use-studio.ts         |  41 +++
 .../frontend/src/hooks/use-modifier-held.ts   |  27 ++
 15 files changed, 800 insertions(+), 257 deletions(-)
 create mode 100644 surfsense_local/frontend/src/features/studio/use-studio.test.ts
 create mode 100644 surfsense_local/frontend/src/hooks/use-modifier-held.ts

diff --git a/surfsense_local/backend/modules/artifacts/router.py b/surfsense_local/backend/modules/artifacts/router.py
index 970dd6ef4c..543a58887b 100644
--- a/surfsense_local/backend/modules/artifacts/router.py
+++ b/surfsense_local/backend/modules/artifacts/router.py
@@ -14,7 +14,7 @@
     FormatRead,
     StudioJobCreate,
 )
-from modules.artifacts.service import create_artifact_job, list_formats
+from modules.artifacts.service import create_artifact_job, list_formats, retry_artifact
 from modules.documents.models import Document, DocumentType
 from modules.workspaces.dependencies import WorkspaceDep
 from shared.config import get_storage_settings
@@ -102,6 +102,16 @@ def read_artifact_file(artifact: ArtifactDep, role: ArtifactFileRole) -> FileRes
     )
 
 
+@router.post(
+    "/artifacts/{artifact_id}/retry",
+    response_model=ArtifactRead,
+    summary="Requeue a failed artifact",
+)
+def retry_studio_artifact(artifact: ArtifactDep, session: SessionDep) -> ArtifactRead:
+    artifact = retry_artifact(session, artifact)
+    return ArtifactRead.of(artifact)
+
+
 @router.delete(
     "/artifacts/{artifact_id}",
     status_code=status.HTTP_204_NO_CONTENT,
diff --git a/surfsense_local/backend/modules/artifacts/service.py b/surfsense_local/backend/modules/artifacts/service.py
index a504850a6e..e8a2aff892 100644
--- a/surfsense_local/backend/modules/artifacts/service.py
+++ b/surfsense_local/backend/modules/artifacts/service.py
@@ -86,6 +86,28 @@ def create_artifact_job(
     return artifact
 
 
+def retry_artifact(session: Session, artifact: Artifact) -> Artifact:
+    """Requeue a failed artifact's generation, in place.
+
+    Mirrors retry_document: the same artifact_metadata (sources, prompt,
+    options) that created the artifact is still there, so this just resets
+    the backing document and re-enqueues the same job — no new row.
+    """
+    document = artifact.document
+    if document.status is not DocumentStatus.FAILED:
+        raise HTTPException(
+            status.HTTP_409_CONFLICT, "only a failed artifact can be retried"
+        )
+
+    document.status = DocumentStatus.PENDING
+    document.error_message = None
+    session.commit()
+
+    studio_job(artifact.id)
+    logger.info("studio: retrying artifact %s", artifact.id)
+    return artifact
+
+
 def _resolve_sources(
     session: Session, workspace: Workspace, document_ids: list[int]
 ) -> list[Document]:
diff --git a/surfsense_local/backend/tests/integration/artifacts/test_routes.py b/surfsense_local/backend/tests/integration/artifacts/test_routes.py
index ecc19b3358..5e2fe8d7f2 100644
--- a/surfsense_local/backend/tests/integration/artifacts/test_routes.py
+++ b/surfsense_local/backend/tests/integration/artifacts/test_routes.py
@@ -1,10 +1,11 @@
 import pytest
 from httpx import AsyncClient
-from sqlalchemy import Engine
+from sqlalchemy import Engine, text
 
 from modules.documents.models import Document, DocumentStatus, DocumentType
 from modules.llm.models import ModelRole, SelectedModel
 from shared.db import create_session_factory
+from shared.queue import huey
 
 pytestmark = pytest.mark.integration
 
@@ -144,6 +145,51 @@ async def test_a_job_waits_for_a_source_to_index(
     assert response.status_code == 409
 
 
+async def test_a_failed_artifact_can_be_retried(
+    client: AsyncClient, engine: Engine, workspace_id: int, choose_model: None
+) -> None:
+    """Mirrors document retry: reset the backing document and requeue in place."""
+    source_id = make_ready_source(engine, workspace_id)
+    created = await client.post(
+        f"/workspaces/{workspace_id}/studio/jobs",
+        json={"format": "summary", "document_ids": [source_id]},
+    )
+    artifact_id = created.json()["id"]
+    document_id = created.json()["document_id"]
+    with engine.begin() as connection:
+        connection.execute(
+            text(
+                "UPDATE documents SET status = 'failed', "
+                "error_message = 'model server down' WHERE id = :id"
+            ),
+            {"id": document_id},
+        )
+    huey.flush()
+
+    response = await client.post(f"/artifacts/{artifact_id}/retry")
+
+    assert response.status_code == 200
+    assert response.json()["status"] == "pending"
+    assert response.json()["error_message"] is None
+    assert [job.args for job in huey.pending()] == [(artifact_id,)]
+
+
+async def test_only_a_failed_artifact_is_retried(
+    client: AsyncClient, engine: Engine, workspace_id: int, choose_model: None
+) -> None:
+    """Requeueing one already pending or processing would run it twice."""
+    source_id = make_ready_source(engine, workspace_id)
+    created = await client.post(
+        f"/workspaces/{workspace_id}/studio/jobs",
+        json={"format": "summary", "document_ids": [source_id]},
+    )
+    artifact_id = created.json()["id"]
+
+    response = await client.post(f"/artifacts/{artifact_id}/retry")
+
+    assert response.status_code == 409
+
+
 async def test_an_artifact_can_be_deleted(
     client: AsyncClient, engine: Engine, workspace_id: int, choose_model: None
 ) -> None:
diff --git a/surfsense_local/frontend/src/components/ui/sonner.tsx b/surfsense_local/frontend/src/components/ui/sonner.tsx
index 93ad68e544..35efc5f859 100644
--- a/surfsense_local/frontend/src/components/ui/sonner.tsx
+++ b/surfsense_local/frontend/src/components/ui/sonner.tsx
@@ -9,6 +9,10 @@ function Toaster(props: ToasterProps) {
     <Sonner
       theme={theme}
       className="toaster group"
+      // Without this, every type (success/error/warning/info) renders with
+      // the same --normal-* colors below — error looked identical to a
+      // plain toast. This turns on sonner's own per-type palette.
+      richColors
       icons={{ success: <CheckCircle2Icon className="size-4" /> }}
       style={
         {
diff --git a/surfsense_local/frontend/src/features/chat/thread-list.tsx b/surfsense_local/frontend/src/features/chat/thread-list.tsx
index 7c3c7713a4..19d921674a 100644
--- a/surfsense_local/frontend/src/features/chat/thread-list.tsx
+++ b/surfsense_local/frontend/src/features/chat/thread-list.tsx
@@ -162,7 +162,7 @@ export function ThreadList({
 
   return (
     <aside className="flex h-full min-w-0 flex-col border-r bg-background">
-      <header className="space-y-3 px-3 py-3">
+      <header className="space-y-6 px-3 py-3">
         <h2 className="truncate px-1 font-heading text-lg font-medium text-foreground select-none">
           SurfSense
         </h2>
diff --git a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
index 84c1cab641..5c9d6c709a 100644
--- a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
+++ b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
@@ -157,7 +157,11 @@ function WorkspaceDashboard({
                 icon: UnplugIcon,
                 badge: "Coming soon",
                 // TODO: open the plugins panel once it exists.
-                onClick: () => toast.info("Plugins are coming soon"),
+                onClick: () =>
+                  toast.info("Plugins are coming soon", {
+                    description:
+                      "Connect external tools to extend what SurfSense can do. We're still polishing this.",
+                  }),
               },
             ]}
           />
@@ -257,6 +261,7 @@ function WorkspaceDashboard({
                     setInspect({ kind: "artifact", artifactId })
                   }}
                   onDelete={(artifactId) => void studio.remove(artifactId)}
+                  onRetry={(artifactId) => void studio.retry(artifactId)}
                 />
               }
             />
diff --git a/surfsense_local/frontend/src/features/sources/source-upload.test.tsx b/surfsense_local/frontend/src/features/sources/source-upload.test.tsx
index 0f94668a7e..c3cbaf4e36 100644
--- a/surfsense_local/frontend/src/features/sources/source-upload.test.tsx
+++ b/surfsense_local/frontend/src/features/sources/source-upload.test.tsx
@@ -186,33 +186,126 @@ describe("source upload", () => {
     expect(actionsButton.className).toContain("focus-visible:opacity-100")
   })
 
+  it("shows a generic retry hint on plain hover of just the icon", async () => {
+    const failed = {
+      ...pendingDocument,
+      title: "failed.pdf",
+      status: "failed" as const,
+      error_message: "connection refused",
+    }
+    const user = userEvent.setup()
+
+    render(
+      <TooltipProvider>
+        <SourcesPanel
+          documents={[failed]}
+          selectedDocumentIds={[]}
+          highlightedDocumentId={null}
+          isLoading={false}
+          isDeleting={false}
+          error={null}
+          onOpen={vi.fn()}
+          onReveal={vi.fn()}
+          onRetry={vi.fn()}
+          onDelete={vi.fn()}
+          onDeleteSelected={vi.fn()}
+          onSelectionChange={vi.fn()}
+        />
+      </TooltipProvider>
+    )
+
+    const retryIcon = screen.getByLabelText(
+      "Ingestion failed. Retry failed.pdf"
+    )
+    await user.hover(retryIcon)
+    const generic = await screen.findByRole("tooltip", {
+      name: "Ingestion failed. Retry again.",
+    })
+    expect(generic.getAttribute("data-side")).toBe("left")
+  })
+
+  it("reveals the real error above the whole row while Ctrl/Cmd is held", async () => {
+    const failed = {
+      ...pendingDocument,
+      title: "failed.pdf",
+      status: "failed" as const,
+      error_message: "connection refused",
+    }
+    const user = userEvent.setup()
+
+    render(
+      <TooltipProvider>
+        <SourcesPanel
+          documents={[failed]}
+          selectedDocumentIds={[]}
+          highlightedDocumentId={null}
+          isLoading={false}
+          isDeleting={false}
+          error={null}
+          onOpen={vi.fn()}
+          onReveal={vi.fn()}
+          onRetry={vi.fn()}
+          onDelete={vi.fn()}
+          onDeleteSelected={vi.fn()}
+          onSelectionChange={vi.fn()}
+        />
+      </TooltipProvider>
+    )
+
+    // Hovering the title, not the icon, proves this covers the whole row.
+    const title = screen.getByRole("button", { name: "failed.pdf" })
+    await user.hover(title)
+    expect(
+      screen.queryByRole("tooltip", { name: "connection refused" })
+    ).toBeNull()
+
+    window.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Control", ctrlKey: true })
+    )
+    const real = await screen.findByRole("tooltip", {
+      name: "connection refused",
+    })
+    expect(real.getAttribute("data-side")).toBe("top")
+
+    window.dispatchEvent(
+      new KeyboardEvent("keyup", { key: "Control", ctrlKey: false })
+    )
+    await waitFor(() =>
+      expect(
+        screen.queryByRole("tooltip", { name: "connection refused" })
+      ).toBeNull()
+    )
+  })
+
   it("offers per-source delete but disables it while processing", async () => {
     const onDelete = vi.fn()
     const user = userEvent.setup()
 
     render(
-      <SourcesPanel
-        documents={[
-          pendingDocument,
-          {
-            ...pendingDocument,
-            id: 2,
-            title: "processing.pdf",
-            status: "processing",
-          },
-        ]}
-        selectedDocumentIds={[]}
-        highlightedDocumentId={null}
-        isLoading={false}
-        isDeleting={false}
-        error={null}
-        onOpen={vi.fn()}
-        onReveal={vi.fn()}
-        onRetry={vi.fn()}
-        onDelete={onDelete}
-        onDeleteSelected={vi.fn()}
-        onSelectionChange={vi.fn()}
-      />
+      <TooltipProvider>
+        <SourcesPanel
+          documents={[
+            pendingDocument,
+            {
+              ...pendingDocument,
+              id: 2,
+              title: "processing.pdf",
+              status: "processing",
+            },
+          ]}
+          selectedDocumentIds={[]}
+          highlightedDocumentId={null}
+          isLoading={false}
+          isDeleting={false}
+          error={null}
+          onOpen={vi.fn()}
+          onReveal={vi.fn()}
+          onRetry={vi.fn()}
+          onDelete={onDelete}
+          onDeleteSelected={vi.fn()}
+          onSelectionChange={vi.fn()}
+        />
+      </TooltipProvider>
     )
 
     await user.click(
diff --git a/surfsense_local/frontend/src/features/sources/sources-panel.tsx b/surfsense_local/frontend/src/features/sources/sources-panel.tsx
index 0745a251fe..7dcea5f4aa 100644
--- a/surfsense_local/frontend/src/features/sources/sources-panel.tsx
+++ b/surfsense_local/frontend/src/features/sources/sources-panel.tsx
@@ -50,6 +50,7 @@ import {
 import { ScrollShadow } from "@/components/ui/scroll-shadow"
 import { SkeletonSlabs } from "@/components/ui/skeleton"
 import { SOURCE_FILE_ACCEPT, type WorkspaceDocument } from "./api"
+import { useModifierHeld } from "@/hooks/use-modifier-held"
 import { Input } from "@/components/ui/input"
 import { Spinner } from "@/components/ui/spinner"
 import {
@@ -89,147 +90,168 @@ function SelectableSourceRow({
   const processing = document.status === "processing"
   const openable = ready && document.document_type === "FILE"
   const [dropdownOpen, setDropdownOpen] = useState(false)
+  const [rowHovered, setRowHovered] = useState(false)
+  // A developer aid: holding Ctrl/Cmd while hovering anywhere on a failed
+  // row (not just the retry icon) surfaces the actual error above the row.
+  const modifierHeld = useModifierHeld()
 
   return (
-    <div
-      ref={rowRef}
-      aria-current={highlighted ? "true" : undefined}
-      className={cn(
-        "group group/source relative flex h-8 w-full min-w-0 items-center gap-1.5 overflow-hidden rounded-lg border border-transparent pr-2 pl-1 select-none hover:bg-muted dark:hover:bg-muted/50",
-        highlighted && "border-ring",
-        selected && "bg-sidebar-accent text-white",
-        dropdownOpen && "bg-muted dark:bg-muted/50"
-      )}
-    >
-      <span className="relative flex size-7 shrink-0 items-center justify-center">
-        {ready ? (
-          <>
-            <Checkbox
-              checked={selected}
-              aria-label={`Select ${document.title}`}
-              className={cn(
-                "peer absolute z-10 transition-opacity duration-150",
-                selected
-                  ? "opacity-100"
-                  : "pointer-events-none opacity-0 group-hover/source:pointer-events-auto group-hover/source:opacity-100 focus-visible:pointer-events-auto focus-visible:opacity-100"
-              )}
-              onClick={(event) => event.stopPropagation()}
-              onCheckedChange={(checked) => onSelectedChange(checked === true)}
-            />
-            <span
-              className={cn(
-                "pointer-events-none absolute inset-0 flex items-center justify-center text-muted-foreground transition-opacity duration-150",
-                selected
-                  ? "opacity-0"
-                  : "opacity-100 group-hover/source:opacity-0 peer-focus-visible:opacity-0"
-              )}
-            >
-              {document.document_type === "NOTE" ? (
-                <NotebookTextIcon className="size-4.5" />
-              ) : (
-                <FileIcon className="size-4.5" />
-              )}
-            </span>
-          </>
-        ) : null}
-        {ingesting ? (
-          <Spinner
-            className="size-4.5 text-muted-foreground"
-            aria-label={`Processing ${document.title}`}
-          />
-        ) : null}
-        {failed ? (
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <Button
-                type="button"
-                size="icon-sm"
-                variant="ghost"
-                aria-label={`Ingestion failed. Retry ${document.title}`}
-                className="relative hover:bg-transparent"
-                onClick={onRetry}
+    <Tooltip open={failed && modifierHeld && rowHovered}>
+      <TooltipTrigger asChild>
+        <div
+          ref={rowRef}
+          aria-current={highlighted ? "true" : undefined}
+          className={cn(
+            "group group/source relative flex h-8 w-full min-w-0 items-center gap-1.5 overflow-hidden rounded-lg border border-transparent pr-2 pl-1 select-none hover:bg-muted dark:hover:bg-muted/50",
+            highlighted && "border-ring",
+            selected && "bg-sidebar-accent text-white",
+            dropdownOpen && "bg-muted dark:bg-muted/50"
+          )}
+          onMouseEnter={() => setRowHovered(true)}
+          onMouseLeave={() => setRowHovered(false)}
+        >
+          <span className="relative flex size-7 shrink-0 items-center justify-center">
+            {ready ? (
+              <>
+                <Checkbox
+                  checked={selected}
+                  aria-label={`Select ${document.title}`}
+                  className={cn(
+                    "peer absolute z-10 transition-opacity duration-150",
+                    selected
+                      ? "opacity-100"
+                      : "pointer-events-none opacity-0 group-hover/source:pointer-events-auto group-hover/source:opacity-100 focus-visible:pointer-events-auto focus-visible:opacity-100"
+                  )}
+                  onClick={(event) => event.stopPropagation()}
+                  onCheckedChange={(checked) =>
+                    onSelectedChange(checked === true)
+                  }
+                />
+                <span
+                  className={cn(
+                    "pointer-events-none absolute inset-0 flex items-center justify-center text-muted-foreground transition-opacity duration-150",
+                    selected
+                      ? "opacity-0"
+                      : "opacity-100 group-hover/source:opacity-0 peer-focus-visible:opacity-0"
+                  )}
+                >
+                  {document.document_type === "NOTE" ? (
+                    <NotebookTextIcon className="size-4.5" />
+                  ) : (
+                    <FileIcon className="size-4.5" />
+                  )}
+                </span>
+              </>
+            ) : null}
+            {ingesting ? (
+              <Spinner
+                className="size-4.5 text-muted-foreground"
+                aria-label={`Processing ${document.title}`}
+              />
+            ) : null}
+            {failed ? (
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <Button
+                    type="button"
+                    size="icon-sm"
+                    variant="ghost"
+                    aria-label={`Ingestion failed. Retry ${document.title}`}
+                    className="relative hover:bg-transparent"
+                    onClick={onRetry}
+                  >
+                    <Alert02Icon className="size-4.5 text-destructive transition-opacity duration-150 group-hover/source:opacity-0 group-focus-visible/button:opacity-0" />
+                    <RefreshCwIcon className="absolute inset-0 m-auto size-4.5 text-muted-foreground opacity-0 transition-opacity duration-150 group-hover/source:opacity-100 group-focus-visible/button:opacity-100" />
+                  </Button>
+                </TooltipTrigger>
+                <TooltipContent side="left" collisionPadding={8}>
+                  Ingestion failed. Retry again.
+                </TooltipContent>
+              </Tooltip>
+            ) : null}
+          </span>
+          <button
+            type="button"
+            disabled={!openable}
+            className={cn(
+              "sidebar-row-title-fade min-w-0 flex-1 overflow-hidden rounded-sm text-left text-sm font-normal whitespace-nowrap outline-none focus-visible:ring-2 focus-visible:ring-ring/50 disabled:cursor-default",
+              dropdownOpen && "sidebar-row-title-fade-actions"
+            )}
+            onClick={openable ? onOpen : undefined}
+          >
+            {document.title}
+          </button>
+          <div className="absolute inset-y-0 right-0 flex items-center pr-1">
+            <DropdownMenu open={dropdownOpen} onOpenChange={setDropdownOpen}>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  type="button"
+                  size="icon-sm"
+                  variant="ghost"
+                  className="size-6 shrink-0 opacity-0 group-hover/source:opacity-100 hover:bg-transparent focus-visible:opacity-100 active:translate-y-px data-[state=open]:bg-accent data-[state=open]:opacity-100"
+                  aria-label={`Actions for ${document.title}`}
+                >
+                  <EllipsisIcon />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent
+                align="end"
+                sideOffset={8}
+                className="min-w-40"
               >
-                <Alert02Icon className="size-4.5 text-destructive transition-opacity duration-150 group-hover/source:opacity-0 group-focus-visible/button:opacity-0" />
-                <RefreshCwIcon className="absolute inset-0 m-auto size-4.5 text-muted-foreground opacity-0 transition-opacity duration-150 group-hover/source:opacity-100 group-focus-visible/button:opacity-100" />
-              </Button>
-            </TooltipTrigger>
-            <TooltipContent side="left" collisionPadding={8}>
-              Ingestion failed. Retry
-            </TooltipContent>
-          </Tooltip>
-        ) : null}
-      </span>
-      <button
-        type="button"
-        disabled={!openable}
-        className={cn(
-          "sidebar-row-title-fade min-w-0 flex-1 overflow-hidden rounded-sm text-left text-sm font-normal whitespace-nowrap outline-none focus-visible:ring-2 focus-visible:ring-ring/50 disabled:cursor-default",
-          dropdownOpen && "sidebar-row-title-fade-actions"
-        )}
-        onClick={openable ? onOpen : undefined}
-      >
-        {document.title}
-      </button>
-      <div className="absolute inset-y-0 right-0 flex items-center pr-1">
-        <DropdownMenu open={dropdownOpen} onOpenChange={setDropdownOpen}>
-          <DropdownMenuTrigger asChild>
-            <Button
-              type="button"
-              size="icon-sm"
-              variant="ghost"
-              className="size-6 shrink-0 opacity-0 group-hover/source:opacity-100 hover:bg-transparent focus-visible:opacity-100 active:translate-y-px data-[state=open]:bg-accent data-[state=open]:opacity-100"
-              aria-label={`Actions for ${document.title}`}
-            >
-              <EllipsisIcon />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end" sideOffset={8} className="min-w-40">
-            <DropdownMenuGroup>
-              {openable ? (
-                <>
-                  <DropdownMenuItem onSelect={onOpen}>
-                    <ViewIcon />
-                    Open
-                  </DropdownMenuItem>
-                  <DropdownMenuItem onSelect={onReveal}>
-                    <FolderOpenIcon />
-                    Show in folder
+                <DropdownMenuGroup>
+                  {openable ? (
+                    <>
+                      <DropdownMenuItem onSelect={onOpen}>
+                        <ViewIcon />
+                        Open
+                      </DropdownMenuItem>
+                      <DropdownMenuItem onSelect={onReveal}>
+                        <FolderOpenIcon />
+                        Show in folder
+                      </DropdownMenuItem>
+                    </>
+                  ) : null}
+                  {ready ? (
+                    <DropdownMenuItem
+                      onSelect={() => onSelectedChange(!selected)}
+                    >
+                      {selected ? <XIcon /> : <SquareDashedMousePointerIcon />}
+                      {selected ? "Deselect" : "Select"}
+                    </DropdownMenuItem>
+                  ) : null}
+                  {failed ? (
+                    <DropdownMenuItem onSelect={onRetry}>
+                      <RefreshCwIcon />
+                      Retry
+                    </DropdownMenuItem>
+                  ) : null}
+                  {ingesting ? (
+                    <DropdownMenuItem disabled>
+                      <span className="flex animate-spin" aria-hidden="true">
+                        <Loader2Icon />
+                      </span>
+                      Processing
+                    </DropdownMenuItem>
+                  ) : null}
+                  <DropdownMenuItem
+                    variant="destructive"
+                    disabled={processing || isDeleting}
+                    onSelect={onDelete}
+                  >
+                    <Trash2Icon />
+                    Delete
                   </DropdownMenuItem>
-                </>
-              ) : null}
-              {ready ? (
-                <DropdownMenuItem onSelect={() => onSelectedChange(!selected)}>
-                  {selected ? <XIcon /> : <SquareDashedMousePointerIcon />}
-                  {selected ? "Deselect" : "Select"}
-                </DropdownMenuItem>
-              ) : null}
-              {failed ? (
-                <DropdownMenuItem onSelect={onRetry}>
-                  <RefreshCwIcon />
-                  Retry
-                </DropdownMenuItem>
-              ) : null}
-              {ingesting ? (
-                <DropdownMenuItem disabled>
-                  <span className="flex animate-spin" aria-hidden="true">
-                    <Loader2Icon />
-                  </span>
-                  Processing
-                </DropdownMenuItem>
-              ) : null}
-              <DropdownMenuItem
-                variant="destructive"
-                disabled={processing || isDeleting}
-                onSelect={onDelete}
-              >
-                <Trash2Icon />
-                Delete
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-    </div>
+                </DropdownMenuGroup>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
+        </div>
+      </TooltipTrigger>
+      <TooltipContent side="top" collisionPadding={8}>
+        {document.error_message ?? "Ingestion failed"}
+      </TooltipContent>
+    </Tooltip>
   )
 }
 
diff --git a/surfsense_local/frontend/src/features/studio/api.ts b/surfsense_local/frontend/src/features/studio/api.ts
index 6f6922ece4..e24d76d376 100644
--- a/surfsense_local/frontend/src/features/studio/api.ts
+++ b/surfsense_local/frontend/src/features/studio/api.ts
@@ -78,6 +78,16 @@ export function readArtifact(
   return requestJson<ArtifactDetail>(`/artifacts/${artifactId}`, { signal })
 }
 
+export function retryArtifact(
+  artifactId: number,
+  signal?: AbortSignal
+): Promise<Artifact> {
+  return requestJson<Artifact>(`/artifacts/${artifactId}/retry`, {
+    method: "POST",
+    signal,
+  })
+}
+
 export function deleteArtifact(
   artifactId: number,
   signal?: AbortSignal
diff --git a/surfsense_local/frontend/src/features/studio/artifact-list.test.tsx b/surfsense_local/frontend/src/features/studio/artifact-list.test.tsx
index 43fe0dd001..456b8ef322 100644
--- a/surfsense_local/frontend/src/features/studio/artifact-list.test.tsx
+++ b/surfsense_local/frontend/src/features/studio/artifact-list.test.tsx
@@ -1,4 +1,4 @@
-import { cleanup, render, screen } from "@testing-library/react"
+import { cleanup, render, screen, waitFor } from "@testing-library/react"
 import userEvent from "@testing-library/user-event"
 import { afterEach, describe, expect, it, vi } from "vitest"
 
@@ -26,6 +26,7 @@ function renderList(props: Partial<Parameters<typeof ArtifactList>[0]> = {}) {
         artifacts={[artifact]}
         onOpen={vi.fn()}
         onDelete={vi.fn()}
+        onRetry={vi.fn()}
         {...props}
       />
     </TooltipProvider>
@@ -71,12 +72,15 @@ describe("artifact list", () => {
       screen.getByRole("status", { name: "Processing Weekly summary" })
     ).toBeTruthy()
     expect(
-      (screen.getByRole("button", { name: "Weekly summary" }) as HTMLButtonElement)
-        .disabled
+      (
+        screen.getByRole("button", {
+          name: "Weekly summary",
+        }) as HTMLButtonElement
+      ).disabled
     ).toBe(true)
   })
 
-  it("shows the stored failure reason without opening the artifact", async () => {
+  it("disables opening a failed artifact and offers a generic retry hint on hover", async () => {
     const onOpen = vi.fn()
     const user = userEvent.setup()
     renderList({
@@ -93,9 +97,21 @@ describe("artifact list", () => {
     })
 
     expect(screen.queryByText("failed")).toBeNull()
+    const retryIcon = screen.getByLabelText(
+      "Generation failed. Retry Flashcards"
+    )
+    await user.hover(retryIcon)
+    // The real error is reserved for Ctrl/Cmd+hover — see the test below.
     expect(
-      screen.getByLabelText("ConnectError: All connection attempts failed")
+      await screen.findByRole("tooltip", {
+        name: "Generation failed. Retry again.",
+      })
     ).toBeTruthy()
+    expect(
+      screen.queryByRole("tooltip", {
+        name: "ConnectError: All connection attempts failed",
+      })
+    ).toBeNull()
     const failed = screen.getByRole("button", { name: "Flashcards" })
     expect((failed as HTMLButtonElement).disabled).toBe(true)
     await user.click(failed)
@@ -115,4 +131,69 @@ describe("artifact list", () => {
     await user.click(screen.getByRole("button", { name: "Delete artifact" }))
     expect(onDelete).toHaveBeenCalledWith(12)
   })
+
+  it("retries a failed artifact from the icon and from the dropdown", async () => {
+    const onRetry = vi.fn()
+    const user = userEvent.setup()
+    renderList({
+      artifacts: [{ ...artifact, status: "failed", error_message: "boom" }],
+      onRetry,
+    })
+
+    await user.click(
+      screen.getByLabelText("Generation failed. Retry Weekly summary")
+    )
+    expect(onRetry).toHaveBeenCalledExactlyOnceWith(12)
+
+    await user.click(
+      screen.getByRole("button", { name: "Actions for Weekly summary" })
+    )
+    expect(screen.queryByRole("menuitem", { name: "Open" })).toBeNull()
+    await user.click(screen.getByRole("menuitem", { name: "Retry" }))
+    expect(onRetry).toHaveBeenCalledTimes(2)
+  })
+
+  it("shows a generic retry hint on plain hover of just the icon", async () => {
+    const user = userEvent.setup()
+    renderList({
+      artifacts: [{ ...artifact, status: "failed", error_message: "boom" }],
+    })
+
+    const retryIcon = screen.getByLabelText(
+      "Generation failed. Retry Weekly summary"
+    )
+    await user.hover(retryIcon)
+    const generic = await screen.findByRole("tooltip", {
+      name: "Generation failed. Retry again.",
+    })
+    expect(generic.getAttribute("data-side")).toBe("left")
+  })
+
+  it("reveals the real error above the whole row while Ctrl/Cmd is held", async () => {
+    const user = userEvent.setup()
+    renderList({
+      artifacts: [{ ...artifact, status: "failed", error_message: "boom" }],
+    })
+
+    // Hovering the title, not the icon, proves this covers the whole row.
+    const title = screen.getByRole("button", { name: "Weekly summary" })
+    await user.hover(title)
+    expect(screen.queryByRole("tooltip", { name: "boom" })).toBeNull()
+
+    window.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Control", ctrlKey: true })
+    )
+    const real = await screen.findByRole("tooltip", { name: "boom" })
+    expect(real.getAttribute("data-side")).toBe("top")
+
+    window.dispatchEvent(
+      new KeyboardEvent("keyup", { key: "Control", ctrlKey: false })
+    )
+    // Radix keeps the node mounted with data-state="closed" through its exit
+    // animation, which jsdom never finishes — so wait for it to go rather
+    // than asserting synchronously.
+    await waitFor(() =>
+      expect(screen.queryByRole("tooltip", { name: "boom" })).toBeNull()
+    )
+  })
 })
diff --git a/surfsense_local/frontend/src/features/studio/artifact-list.tsx b/surfsense_local/frontend/src/features/studio/artifact-list.tsx
index d38de4696b..264ea1bf77 100644
--- a/surfsense_local/frontend/src/features/studio/artifact-list.tsx
+++ b/surfsense_local/frontend/src/features/studio/artifact-list.tsx
@@ -5,6 +5,7 @@ import {
   FileIcon,
   FileTextIcon,
   Loader2Icon,
+  RefreshCwIcon,
   Trash2Icon,
   ViewIcon,
 } from "@/components/ui/icons"
@@ -42,6 +43,7 @@ import {
   TooltipContent,
   TooltipTrigger,
 } from "@/components/ui/tooltip"
+import { useModifierHeld } from "@/hooks/use-modifier-held"
 import { cn } from "@/lib/utils"
 
 import type { Artifact } from "./api"
@@ -51,10 +53,12 @@ function ArtifactRow({
   artifact,
   onOpen,
   onDelete,
+  onRetry,
 }: {
   artifact: Artifact
   onOpen: () => void
   onDelete: () => void
+  onRetry: () => void
 }) {
   const ready = artifact.status === "ready"
   const failed = artifact.status === "failed"
@@ -62,97 +66,123 @@ function ArtifactRow({
     artifact.status === "pending" || artifact.status === "processing"
   const processing = artifact.status === "processing"
   const [dropdownOpen, setDropdownOpen] = useState(false)
+  const [rowHovered, setRowHovered] = useState(false)
+  // A developer aid: holding Ctrl/Cmd while hovering anywhere on a failed
+  // row (not just the retry icon) surfaces the actual error above the row.
+  const modifierHeld = useModifierHeld()
   const FormatIcon = FORMAT_ICONS[artifact.format] ?? FileIcon
+  const errorMessage = artifact.error_message ?? "Generation failed"
 
   return (
-    <div
-      className={cn(
-        "group group/artifact relative flex h-8 w-full min-w-0 items-center gap-1.5 overflow-hidden rounded-lg border border-transparent pr-2 pl-1 hover:bg-muted dark:hover:bg-muted/50",
-        dropdownOpen && "bg-muted dark:bg-muted/50"
-      )}
-    >
-      <span className="relative flex size-7 shrink-0 items-center justify-center">
-        {ready ? (
-          <FormatIcon className="size-4.5 text-muted-foreground" />
-        ) : null}
-        {ingesting ? (
-          <Spinner
-            className="size-4.5 text-muted-foreground"
-            aria-label={`Processing ${artifact.title}`}
-          />
-        ) : null}
-        {failed ? (
-          <Tooltip>
-            <TooltipTrigger asChild>
-              <Button
-                type="button"
-                size="icon-sm"
-                variant="ghost"
-                aria-label={artifact.error_message ?? "Generation failed"}
-                className="hover:bg-transparent"
-              >
-                <Alert02Icon className="size-4.5 text-destructive" />
-              </Button>
-            </TooltipTrigger>
-            <TooltipContent side="left" collisionPadding={8}>
-              {artifact.error_message ?? "Generation failed"}
-            </TooltipContent>
-          </Tooltip>
-        ) : null}
-      </span>
-      <button
-        type="button"
-        disabled={!ready}
-        className={cn(
-          "sidebar-row-title-fade min-w-0 flex-1 overflow-hidden rounded-sm text-left text-sm font-normal whitespace-nowrap outline-none focus-visible:ring-2 focus-visible:ring-ring/50 disabled:cursor-default",
-          dropdownOpen && "sidebar-row-title-fade-actions"
-        )}
-        onClick={ready ? onOpen : undefined}
-      >
-        {artifact.title}
-      </button>
-      <div className="absolute inset-y-0 right-0 flex items-center pr-1">
-        <DropdownMenu open={dropdownOpen} onOpenChange={setDropdownOpen}>
-          <DropdownMenuTrigger asChild>
-            <Button
-              type="button"
-              size="icon-sm"
-              variant="ghost"
-              className="size-6 shrink-0 opacity-0 group-hover/artifact:opacity-100 hover:bg-transparent focus-visible:opacity-100 active:translate-y-px data-[state=open]:bg-accent data-[state=open]:opacity-100"
-              aria-label={`Actions for ${artifact.title}`}
-            >
-              <EllipsisIcon />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end" sideOffset={8} className="min-w-40">
-            <DropdownMenuGroup>
-              {ready ? (
-                <DropdownMenuItem onSelect={onOpen}>
-                  <ViewIcon />
-                  Open
-                </DropdownMenuItem>
-              ) : null}
-              {ingesting ? (
-                <DropdownMenuItem disabled>
-                  <span className="flex animate-spin" aria-hidden="true">
-                    <Loader2Icon />
-                  </span>
-                  Processing
-                </DropdownMenuItem>
-              ) : null}
-              <DropdownMenuItem
-                variant="destructive"
-                disabled={processing}
-                onSelect={onDelete}
+    <Tooltip open={failed && modifierHeld && rowHovered}>
+      <TooltipTrigger asChild>
+        <div
+          className={cn(
+            "group group/artifact relative flex h-8 w-full min-w-0 items-center gap-1.5 overflow-hidden rounded-lg border border-transparent pr-2 pl-1 hover:bg-muted dark:hover:bg-muted/50",
+            dropdownOpen && "bg-muted dark:bg-muted/50"
+          )}
+          onMouseEnter={() => setRowHovered(true)}
+          onMouseLeave={() => setRowHovered(false)}
+        >
+          <span className="relative flex size-7 shrink-0 items-center justify-center">
+            {ready ? (
+              <FormatIcon className="size-4.5 text-muted-foreground" />
+            ) : null}
+            {ingesting ? (
+              <Spinner
+                className="size-4.5 text-muted-foreground"
+                aria-label={`Processing ${artifact.title}`}
+              />
+            ) : null}
+            {failed ? (
+              <Tooltip>
+                <TooltipTrigger asChild>
+                  <Button
+                    type="button"
+                    size="icon-sm"
+                    variant="ghost"
+                    aria-label={`Generation failed. Retry ${artifact.title}`}
+                    className="relative hover:bg-transparent"
+                    onClick={onRetry}
+                  >
+                    <Alert02Icon className="size-4.5 text-destructive transition-opacity duration-150 group-hover/artifact:opacity-0 group-focus-visible/button:opacity-0" />
+                    <RefreshCwIcon className="absolute inset-0 m-auto size-4.5 text-muted-foreground opacity-0 transition-opacity duration-150 group-hover/artifact:opacity-100 group-focus-visible/button:opacity-100" />
+                  </Button>
+                </TooltipTrigger>
+                <TooltipContent side="left" collisionPadding={8}>
+                  Generation failed. Retry again.
+                </TooltipContent>
+              </Tooltip>
+            ) : null}
+          </span>
+          <button
+            type="button"
+            disabled={!ready}
+            className={cn(
+              "sidebar-row-title-fade min-w-0 flex-1 overflow-hidden rounded-sm text-left text-sm font-normal whitespace-nowrap outline-none focus-visible:ring-2 focus-visible:ring-ring/50 disabled:cursor-default",
+              dropdownOpen && "sidebar-row-title-fade-actions"
+            )}
+            onClick={ready ? onOpen : undefined}
+          >
+            {artifact.title}
+          </button>
+          <div className="absolute inset-y-0 right-0 flex items-center pr-1">
+            <DropdownMenu open={dropdownOpen} onOpenChange={setDropdownOpen}>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  type="button"
+                  size="icon-sm"
+                  variant="ghost"
+                  className="size-6 shrink-0 opacity-0 group-hover/artifact:opacity-100 hover:bg-transparent focus-visible:opacity-100 active:translate-y-px data-[state=open]:bg-accent data-[state=open]:opacity-100"
+                  aria-label={`Actions for ${artifact.title}`}
+                >
+                  <EllipsisIcon />
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent
+                align="end"
+                sideOffset={8}
+                className="min-w-40"
               >
-                <Trash2Icon />
-                Delete
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-    </div>
+                <DropdownMenuGroup>
+                  {ready ? (
+                    <DropdownMenuItem onSelect={onOpen}>
+                      <ViewIcon />
+                      Open
+                    </DropdownMenuItem>
+                  ) : null}
+                  {failed ? (
+                    <DropdownMenuItem onSelect={onRetry}>
+                      <RefreshCwIcon />
+                      Retry
+                    </DropdownMenuItem>
+                  ) : null}
+                  {ingesting ? (
+                    <DropdownMenuItem disabled>
+                      <span className="flex animate-spin" aria-hidden="true">
+                        <Loader2Icon />
+                      </span>
+                      Processing
+                    </DropdownMenuItem>
+                  ) : null}
+                  <DropdownMenuItem
+                    variant="destructive"
+                    disabled={processing}
+                    onSelect={onDelete}
+                  >
+                    <Trash2Icon />
+                    Delete
+                  </DropdownMenuItem>
+                </DropdownMenuGroup>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
+        </div>
+      </TooltipTrigger>
+      <TooltipContent side="top" collisionPadding={8}>
+        {errorMessage}
+      </TooltipContent>
+    </Tooltip>
   )
 }
 
@@ -161,11 +191,13 @@ export function ArtifactList({
   isLoading = false,
   onOpen,
   onDelete,
+  onRetry,
 }: {
   artifacts: Artifact[]
   isLoading?: boolean
   onOpen: (id: number) => void
   onDelete: (id: number) => void
+  onRetry: (id: number) => void
 }) {
   const [deleteTarget, setDeleteTarget] = useState<Artifact | null>(null)
 
@@ -205,6 +237,7 @@ export function ArtifactList({
                 artifact={artifact}
                 onOpen={() => onOpen(artifact.id)}
                 onDelete={() => setDeleteTarget(artifact)}
+                onRetry={() => onRetry(artifact.id)}
               />
             ))}
           </div>
@@ -222,8 +255,8 @@ export function ArtifactList({
               Delete {deleteTarget?.title ?? "this artifact"}?
             </AlertDialogTitle>
             <AlertDialogDescription>
-              This permanently deletes{" "}
-              {deleteTarget?.title ?? "this artifact"} and its generated files.
+              This permanently deletes {deleteTarget?.title ?? "this artifact"}{" "}
+              and its generated files.
             </AlertDialogDescription>
           </AlertDialogHeader>
           <AlertDialogFooter>
diff --git a/surfsense_local/frontend/src/features/studio/studio-panel.test.tsx b/surfsense_local/frontend/src/features/studio/studio-panel.test.tsx
index 71a36e8294..6651031c99 100644
--- a/surfsense_local/frontend/src/features/studio/studio-panel.test.tsx
+++ b/surfsense_local/frontend/src/features/studio/studio-panel.test.tsx
@@ -50,6 +50,7 @@ function StudioHarness({
         isLoading={studio.isLoading}
         onOpen={vi.fn()}
         onDelete={(id) => void studio.remove(id)}
+        onRetry={(id) => void studio.retry(id)}
       />
     </>
   )
diff --git a/surfsense_local/frontend/src/features/studio/use-studio.test.ts b/surfsense_local/frontend/src/features/studio/use-studio.test.ts
new file mode 100644
index 0000000000..7659794c8f
--- /dev/null
+++ b/surfsense_local/frontend/src/features/studio/use-studio.test.ts
@@ -0,0 +1,148 @@
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { renderHook, waitFor } from "@testing-library/react"
+import { toast } from "sonner"
+
+import { useStudio } from "./use-studio"
+import type { Artifact } from "./api"
+
+vi.mock("sonner", () => ({
+  toast: {
+    success: vi.fn(),
+    error: vi.fn(),
+  },
+}))
+
+function artifact(overrides: Partial<Artifact> = {}): Artifact {
+  return {
+    id: 1,
+    document_id: 1,
+    format: "summary",
+    generation: 1,
+    title: "Summary of the source",
+    status: "processing",
+    error_message: null,
+    created_at: "2026-09-15T00:00:00Z",
+    updated_at: "2026-09-15T00:00:00Z",
+    ...overrides,
+  }
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals()
+  vi.mocked(toast.success).mockClear()
+  vi.mocked(toast.error).mockClear()
+})
+
+describe("useStudio", () => {
+  it("shows a success toast once a running artifact turns ready", async () => {
+    const responses: unknown[] = [
+      [], // GET /studio/formats
+      [artifact()], // GET /artifacts (initial load, still processing)
+      [artifact({ status: "ready" })], // GET /artifacts (poll, now ready)
+    ]
+    const fetchMock = vi.fn(async () => Response.json(responses.shift() ?? []))
+    vi.stubGlobal("fetch", fetchMock)
+
+    renderHook(() => useStudio(1))
+
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(3), {
+      timeout: 4000,
+    })
+
+    expect(toast.success).toHaveBeenCalledExactlyOnceWith(
+      "Summary of the source is ready"
+    )
+
+    // Nothing left running, so no further poll — and no repeat toast.
+    await new Promise((resolve) => setTimeout(resolve, 100))
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+    expect(toast.success).toHaveBeenCalledOnce()
+  }, 8000)
+
+  it("does not toast for an artifact that was already ready", async () => {
+    const responses: unknown[] = [
+      [], // formats
+      [
+        artifact({ status: "ready" }),
+        artifact({ id: 2, status: "processing" }),
+      ],
+      [artifact({ status: "ready" }), artifact({ id: 2, status: "ready" })],
+    ]
+    const fetchMock = vi.fn(async () => Response.json(responses.shift() ?? []))
+    vi.stubGlobal("fetch", fetchMock)
+
+    renderHook(() => useStudio(1))
+
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(3), {
+      timeout: 4000,
+    })
+
+    expect(toast.success).toHaveBeenCalledExactlyOnceWith(
+      "Summary of the source is ready"
+    )
+  }, 8000)
+
+  it("shows an error toast once a running artifact fails, without the raw error", async () => {
+    const responses: unknown[] = [
+      [], // GET /studio/formats
+      [artifact()], // GET /artifacts (initial load, still processing)
+      // A real backend failure here is often a multi-line HTTP exception —
+      // that belongs in the row's own tooltip, never pasted into a toast.
+      [
+        artifact({
+          status: "failed",
+          error_message:
+            "HTTPStatusError: Client error '401 Unauthorized' for url '...'",
+        }),
+      ],
+    ]
+    const fetchMock = vi.fn(async () => Response.json(responses.shift() ?? []))
+    vi.stubGlobal("fetch", fetchMock)
+
+    renderHook(() => useStudio(1))
+
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(3), {
+      timeout: 4000,
+    })
+
+    expect(toast.error).toHaveBeenCalledExactlyOnceWith(
+      "Summary of the source failed",
+      {
+        description:
+          "This artifact couldn't be generated. Retry it from the artifacts tab.",
+      }
+    )
+    const [, options] = vi.mocked(toast.error).mock.calls[0]
+    expect(String(options?.description)).not.toContain("HTTPStatusError")
+    expect(toast.success).not.toHaveBeenCalled()
+
+    // Nothing left running, so no further poll — and no repeat toast.
+    await new Promise((resolve) => setTimeout(resolve, 100))
+    expect(fetchMock).toHaveBeenCalledTimes(3)
+    expect(toast.error).toHaveBeenCalledOnce()
+  }, 8000)
+
+  it("shows the same friendly description even with no error message at all", async () => {
+    const responses: unknown[] = [
+      [],
+      [artifact()],
+      [artifact({ status: "failed", error_message: null })],
+    ]
+    const fetchMock = vi.fn(async () => Response.json(responses.shift() ?? []))
+    vi.stubGlobal("fetch", fetchMock)
+
+    renderHook(() => useStudio(1))
+
+    await waitFor(() => expect(fetchMock).toHaveBeenCalledTimes(3), {
+      timeout: 4000,
+    })
+
+    expect(toast.error).toHaveBeenCalledExactlyOnceWith(
+      "Summary of the source failed",
+      {
+        description:
+          "This artifact couldn't be generated. Retry it from the artifacts tab.",
+      }
+    )
+  }, 8000)
+})
diff --git a/surfsense_local/frontend/src/features/studio/use-studio.ts b/surfsense_local/frontend/src/features/studio/use-studio.ts
index e3dced8dc1..44bb051da6 100644
--- a/surfsense_local/frontend/src/features/studio/use-studio.ts
+++ b/surfsense_local/frontend/src/features/studio/use-studio.ts
@@ -1,10 +1,12 @@
 import { useEffect, useRef, useState } from "react"
+import { toast } from "sonner"
 
 import {
   createJob,
   deleteArtifact,
   listArtifacts,
   listFormats,
+  retryArtifact,
   type Artifact,
   type StudioFormat,
   type StudioJobCreate,
@@ -44,6 +46,12 @@ export function useStudio(workspaceId: number) {
   const [error, setError] = useState<string | null>(null)
   const pollController = useRef<AbortController | null>(null)
   const hasRunning = artifacts.some(isRunning)
+  // Read inside the poll loop instead of closing over `artifacts` directly,
+  // so the diff against each new poll result always sees the latest state.
+  const artifactsRef = useRef(artifacts)
+  useEffect(() => {
+    artifactsRef.current = artifacts
+  }, [artifacts])
 
   useEffect(() => {
     const controller = new AbortController()
@@ -87,6 +95,22 @@ export function useStudio(workspaceId: number) {
           if (pollController.current !== controller) {
             return
           }
+          for (const artifact of next) {
+            const before = artifactsRef.current.find(
+              (candidate) => candidate.id === artifact.id
+            )
+            if (!before || !isRunning(before)) continue
+            if (artifact.status === "ready") {
+              toast.success(`${artifact.title} is ready`)
+            } else if (artifact.status === "failed") {
+              // The raw error (often a multi-line HTTP exception) belongs in
+              // the row's own Ctrl/Cmd-hover tooltip, not a toast.
+              toast.error(`${artifact.title} failed`, {
+                description:
+                  "This artifact couldn't be generated. Retry it from the artifacts tab.",
+              })
+            }
+          }
           setArtifacts(next)
           if (!next.some(isRunning)) {
             return
@@ -127,6 +151,22 @@ export function useStudio(workspaceId: number) {
     }
   }
 
+  // Puts the artifact back to "pending" in state; the poll effect picks it up
+  // the same way it does a freshly created one.
+  const retry = async (artifactId: number) => {
+    setError(null)
+    try {
+      const updated = await retryArtifact(artifactId)
+      setArtifacts((current) =>
+        current.map((artifact) =>
+          artifact.id === artifactId ? updated : artifact
+        )
+      )
+    } catch (cause) {
+      setError(messageFrom(cause))
+    }
+  }
+
   return {
     formats,
     artifacts,
@@ -135,6 +175,7 @@ export function useStudio(workspaceId: number) {
     error,
     create,
     remove,
+    retry,
     clearError: () => setError(null),
   }
 }
diff --git a/surfsense_local/frontend/src/hooks/use-modifier-held.ts b/surfsense_local/frontend/src/hooks/use-modifier-held.ts
new file mode 100644
index 0000000000..fcfeb24581
--- /dev/null
+++ b/surfsense_local/frontend/src/hooks/use-modifier-held.ts
@@ -0,0 +1,27 @@
+import { useEffect, useState } from "react"
+
+// Cmd on macOS, Ctrl everywhere else — the same modifier this app's other
+// shortcuts read via event.metaKey/event.ctrlKey (see theme-provider.tsx).
+export function useModifierHeld() {
+  const [held, setHeld] = useState(false)
+
+  useEffect(() => {
+    const sync = (event: KeyboardEvent) => {
+      setHeld(event.metaKey || event.ctrlKey)
+    }
+    // A window switch (Cmd+Tab) never fires keyup for the held key, so the
+    // state would otherwise get stuck "held" until the next keypress.
+    const clear = () => setHeld(false)
+
+    window.addEventListener("keydown", sync)
+    window.addEventListener("keyup", sync)
+    window.addEventListener("blur", clear)
+    return () => {
+      window.removeEventListener("keydown", sync)
+      window.removeEventListener("keyup", sync)
+      window.removeEventListener("blur", clear)
+    }
+  }, [])
+
+  return held
+}

From 985ad070867e5df14bf29bc8999c361789b2f55b Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 15 Sep 2026 05:07:21 +0530
Subject: [PATCH 7/9] feat(local): add an artifact count badge to the Artifacts
 tab icon

---
 .../dashboard/dashboard-page.test.tsx         | 43 +++++----
 .../src/features/dashboard/dashboard-page.tsx |  1 +
 .../src/features/dashboard/right-panel.tsx    | 93 +++++++++++--------
 3 files changed, 80 insertions(+), 57 deletions(-)

diff --git a/surfsense_local/frontend/src/features/dashboard/dashboard-page.test.tsx b/surfsense_local/frontend/src/features/dashboard/dashboard-page.test.tsx
index 70d076b1f2..b111415adf 100644
--- a/surfsense_local/frontend/src/features/dashboard/dashboard-page.test.tsx
+++ b/surfsense_local/frontend/src/features/dashboard/dashboard-page.test.tsx
@@ -320,9 +320,7 @@ describe("dashboard chat", () => {
     const conversationWhileLoading = screen.getByRole("region", {
       name: "Conversation",
     })
-    expect(
-      await screen.findByRole("textbox", { name: "Message" })
-    ).toBeTruthy()
+    expect(await screen.findByRole("textbox", { name: "Message" })).toBeTruthy()
     expect(
       conversationWhileLoading.querySelector('[data-slot="skeleton"]')
     ).toBeNull()
@@ -392,10 +390,9 @@ describe("dashboard chat", () => {
         { status: 201 }
       )
     )
-    await within(screen.getByRole("region", { name: "Conversation" })).findByRole(
-      "button",
-      { name: "Start a chat" }
-    )
+    await within(
+      screen.getByRole("region", { name: "Conversation" })
+    ).findByRole("button", { name: "Start a chat" })
     await waitFor(() => {
       expect(document.querySelectorAll("time")).toHaveLength(1)
     })
@@ -465,10 +462,9 @@ describe("dashboard chat", () => {
 
     render(page)
     expect(
-      await within(screen.getByRole("region", { name: "Conversation" })).findByRole(
-        "button",
-        { name: "Original title" }
-      )
+      await within(
+        screen.getByRole("region", { name: "Conversation" })
+      ).findByRole("button", { name: "Original title" })
     ).toBeTruthy()
     await user.click(screen.getByRole("button", { name: "New chat" }))
     await waitFor(() => {
@@ -524,7 +520,8 @@ describe("dashboard chat", () => {
         ) {
           return Response.json([])
         }
-        if (path === "/workspaces/1/chat/threads") return Response.json([thread])
+        if (path === "/workspaces/1/chat/threads")
+          return Response.json([thread])
         if (path === "/chat/threads/10/messages") return messagesResponse
         return Response.json({ detail: "not found" }, { status: 404 })
       })
@@ -719,7 +716,7 @@ describe("dashboard chat", () => {
     await user.click(screen.getByRole("button", { name: "Send message" }))
 
     expect(await screen.findByText("Grounded answer")).toBeTruthy()
-    await user.click(screen.getByRole("tab", { name: "Artifacts" }))
+    await user.click(screen.getByRole("tab", { name: /^Artifacts/ }))
     fireEvent.click(screen.getByRole("button", { name: "View cited chunk 30" }))
     expect(await screen.findByText("indexed passage")).toBeTruthy()
     expect(screen.getByText("Cited chunk")).toBeTruthy()
@@ -732,7 +729,7 @@ describe("dashboard chat", () => {
     expect((rail as HTMLElement).style.width).toBe(`${MAIN_RAIL_WIDTH}px`)
     expect(
       screen
-        .getByRole("tab", { name: "Artifacts" })
+        .getByRole("tab", { name: /^Artifacts/ })
         .getAttribute("aria-selected")
     ).toBe("true")
     await user.click(screen.getByRole("tab", { name: "Sources" }))
@@ -1152,13 +1149,15 @@ describe("dashboard chat", () => {
       '[data-state="active"] [data-slot="scroll-shadow-viewport"]'
     )
     expect(
-      sourcesScroll?.contains(screen.getByRole("heading", { name: "All sources" }))
+      sourcesScroll?.contains(
+        screen.getByRole("heading", { name: "All sources" })
+      )
     ).toBe(false)
     expect(
       sourcesScroll?.contains(screen.getByRole("button", { name: "Add" }))
     ).toBe(false)
     expect(sourcesScroll).toBeTruthy()
-    await user.click(screen.getByRole("tab", { name: "Artifacts" }))
+    await user.click(screen.getByRole("tab", { name: /^Artifacts/ }))
     expect(screen.getByRole("heading", { name: "Artifacts" })).toBeTruthy()
     expect(
       screen.getByRole("heading", { name: "All generated artifacts" })
@@ -1193,7 +1192,7 @@ describe("dashboard chat", () => {
     ).toBeTruthy()
     expect(
       screen
-        .getByRole("tab", { name: "Artifacts" })
+        .getByRole("tab", { name: /^Artifacts/ })
         .getAttribute("aria-selected")
     ).toBe("true")
   })
@@ -1239,10 +1238,12 @@ describe("dashboard chat", () => {
     expect(
       await screen.findByRole("complementary", { name: "Workspace sources" })
     ).toBeTruthy()
-    await user.click(screen.getByRole("tab", { name: "Artifacts" }))
+    await user.click(screen.getByRole("tab", { name: /^Artifacts/ }))
     expect(localStorage.getItem(RIGHT_TAB_KEY)).toBe("artifacts")
     expect(
-      screen.getByRole("tab", { name: "Artifacts" }).getAttribute("aria-selected")
+      screen
+        .getByRole("tab", { name: /^Artifacts/ })
+        .getAttribute("aria-selected")
     ).toBe("true")
 
     cleanup()
@@ -1251,7 +1252,9 @@ describe("dashboard chat", () => {
       await screen.findByRole("complementary", { name: "Workspace artifacts" })
     ).toBeTruthy()
     expect(
-      screen.getByRole("tab", { name: "Artifacts" }).getAttribute("aria-selected")
+      screen
+        .getByRole("tab", { name: /^Artifacts/ })
+        .getAttribute("aria-selected")
     ).toBe("true")
   })
 })
diff --git a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
index 5c9d6c709a..93d7c136bc 100644
--- a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
+++ b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
@@ -221,6 +221,7 @@ function WorkspaceDashboard({
                 writeRightTab(next)
                 setTab(next)
               }}
+              artifactCount={studio.artifacts.length}
               studio={
                 <StudioPanel
                   documents={sources.documents}
diff --git a/surfsense_local/frontend/src/features/dashboard/right-panel.tsx b/surfsense_local/frontend/src/features/dashboard/right-panel.tsx
index e334ece8ab..4c922cb2bf 100644
--- a/surfsense_local/frontend/src/features/dashboard/right-panel.tsx
+++ b/surfsense_local/frontend/src/features/dashboard/right-panel.tsx
@@ -18,6 +18,7 @@ export function RightPanel({
   studio,
   sources,
   artifacts,
+  artifactCount,
 }: {
   inspect: ReactNode
   tab: RightTab
@@ -25,12 +26,13 @@ export function RightPanel({
   studio: ReactNode
   sources: ReactNode
   artifacts: ReactNode
+  artifactCount: number
 }) {
   if (inspect) return inspect
 
   return (
     <aside
-      className="flex h-full min-w-0 select-none flex-col border-l bg-background"
+      className="flex h-full min-w-0 flex-col border-l bg-background select-none"
       aria-label={
         tab === "sources" ? "Workspace sources" : "Workspace artifacts"
       }
@@ -44,42 +46,59 @@ export function RightPanel({
           <h2 className="font-heading text-base font-medium">
             {tab === "sources" ? "Sources" : "Artifacts"}
           </h2>
-          <SegmentedControl
-            count={2}
-            selectedIndex={tab === "sources" ? 0 : 1}
-            className="ml-auto h-7 w-14 shrink-0"
-          >
-            <TabsList className="relative h-full bg-transparent p-0">
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <TabsTrigger
-                    value="sources"
-                    aria-label="Sources"
-                    className="h-full px-0 data-[state=active]:bg-transparent data-[state=active]:shadow-none"
-                  >
-                    <FolderLibraryIcon />
-                  </TabsTrigger>
-                </TooltipTrigger>
-                <TooltipContent side="bottom" collisionPadding={8}>
-                  Sources
-                </TooltipContent>
-              </Tooltip>
-              <Tooltip>
-                <TooltipTrigger asChild>
-                  <TabsTrigger
-                    value="artifacts"
-                    aria-label="Artifacts"
-                    className="h-full px-0 data-[state=active]:bg-transparent data-[state=active]:shadow-none"
-                  >
-                    <Shapes01Icon />
-                  </TabsTrigger>
-                </TooltipTrigger>
-                <TooltipContent side="bottom" collisionPadding={8}>
-                  Artifacts
-                </TooltipContent>
-              </Tooltip>
-            </TabsList>
-          </SegmentedControl>
+          {/* The badge lives outside SegmentedControl's own overflow-hidden
+              box (needed for its sliding indicator), anchored to this
+              wrapper's corner instead so it doesn't get clipped. */}
+          <div className="relative ml-auto h-7 w-14 shrink-0">
+            <SegmentedControl
+              count={2}
+              selectedIndex={tab === "sources" ? 0 : 1}
+              className="size-full"
+            >
+              <TabsList className="relative h-full bg-transparent p-0">
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <TabsTrigger
+                      value="sources"
+                      aria-label="Sources"
+                      className="h-full px-0 data-[state=active]:bg-transparent data-[state=active]:shadow-none"
+                    >
+                      <FolderLibraryIcon />
+                    </TabsTrigger>
+                  </TooltipTrigger>
+                  <TooltipContent side="bottom" collisionPadding={8}>
+                    Sources
+                  </TooltipContent>
+                </Tooltip>
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <TabsTrigger
+                      value="artifacts"
+                      aria-label={
+                        artifactCount > 0
+                          ? `Artifacts (${artifactCount})`
+                          : "Artifacts"
+                      }
+                      className="h-full px-0 data-[state=active]:bg-transparent data-[state=active]:shadow-none"
+                    >
+                      <Shapes01Icon />
+                    </TabsTrigger>
+                  </TooltipTrigger>
+                  <TooltipContent side="bottom" collisionPadding={8}>
+                    Artifacts
+                  </TooltipContent>
+                </Tooltip>
+              </TabsList>
+            </SegmentedControl>
+            {artifactCount > 0 ? (
+              <span
+                aria-hidden="true"
+                className="absolute top-0 right-0 flex h-3 min-w-3 items-center justify-center rounded-full bg-primary px-0.5 text-[8px] leading-none font-semibold text-primary-foreground"
+              >
+                {artifactCount}
+              </span>
+            ) : null}
+          </div>
         </header>
         <div className="flex min-h-0 min-w-0 flex-1 flex-col gap-5 overflow-hidden px-3 py-2">
           <div className="shrink-0">{studio}</div>

From b0ea4ad816d69a11db1e4790a67be4a026046897 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 15 Sep 2026 05:11:48 +0530
Subject: [PATCH 8/9] fix(local): swap Network settings icon to
 ComputerEthernetIcon

---
 surfsense_local/frontend/src/components/ui/icons.tsx          | 2 ++
 .../frontend/src/features/settings/settings-dialog.tsx        | 4 ++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/surfsense_local/frontend/src/components/ui/icons.tsx b/surfsense_local/frontend/src/components/ui/icons.tsx
index cbdf2adf16..39740de9d7 100644
--- a/surfsense_local/frontend/src/components/ui/icons.tsx
+++ b/surfsense_local/frontend/src/components/ui/icons.tsx
@@ -14,6 +14,7 @@ import {
   CheckmarkCircle02Icon,
   ChevronDownIcon as ChevronDownIconData,
   ChevronRightIcon as ChevronRightIconData,
+  ComputerEthernetIcon as ComputerEthernetIconData,
   Copy01Icon,
   CpuIcon as CpuIconData,
   Delete02Icon,
@@ -99,6 +100,7 @@ export const CheckCircle2Icon = createIcon(CheckmarkCircle02Icon)
 export const CheckIcon = createIcon(CheckIconData)
 export const ChevronDownIcon = createIcon(ChevronDownIconData)
 export const ChevronRightIcon = createIcon(ChevronRightIconData)
+export const ComputerEthernetIcon = createIcon(ComputerEthernetIconData)
 export const CircleAlertIcon = createIcon(AlertCircleIcon)
 export const CircleStopIcon = createIcon(StopCircleIcon)
 export const CopyIcon = createIcon(Copy01Icon)
diff --git a/surfsense_local/frontend/src/features/settings/settings-dialog.tsx b/surfsense_local/frontend/src/features/settings/settings-dialog.tsx
index a3cef7c5af..3f02142110 100644
--- a/surfsense_local/frontend/src/features/settings/settings-dialog.tsx
+++ b/surfsense_local/frontend/src/features/settings/settings-dialog.tsx
@@ -9,10 +9,10 @@ import {
   DialogTitle,
 } from "@/components/ui/dialog"
 import {
+  ComputerEthernetIcon,
   CpuIcon,
   InformationCircleIcon,
   LicenseIcon,
-  NetworkIcon,
   Settings2Icon,
 } from "@/components/ui/icons"
 import {
@@ -132,7 +132,7 @@ const SETTINGS_SECTIONS = [
   {
     id: "network",
     label: "Network",
-    icon: NetworkIcon,
+    icon: ComputerEthernetIcon,
   },
   {
     id: "license",

From 12ed5c0d84337478039658ebf65dc24adbb54a84 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 15 Sep 2026 05:27:27 +0530
Subject: [PATCH 9/9] feat(local): add a per-workspace type filter to the
 artifacts list

---
 .../frontend/src/components/ui/icons.tsx      |   2 +
 .../src/features/dashboard/dashboard-page.tsx |   2 +
 .../features/studio/artifact-list.test.tsx    |  78 ++++++++
 .../src/features/studio/artifact-list.tsx     | 169 +++++++++++++++++-
 .../src/features/studio/studio-formats.ts     |  36 ++++
 .../src/features/studio/studio-panel.test.tsx |   1 +
 .../src/features/studio/studio-panel.tsx      |  38 +---
 7 files changed, 287 insertions(+), 39 deletions(-)
 create mode 100644 surfsense_local/frontend/src/features/studio/studio-formats.ts

diff --git a/surfsense_local/frontend/src/components/ui/icons.tsx b/surfsense_local/frontend/src/components/ui/icons.tsx
index 39740de9d7..236a1e87f5 100644
--- a/surfsense_local/frontend/src/components/ui/icons.tsx
+++ b/surfsense_local/frontend/src/components/ui/icons.tsx
@@ -26,6 +26,7 @@ import {
   FileAddIcon,
   FileIcon as FileIconData,
   FileTextIcon as FileTextIconData,
+  FilterIcon as FilterIconData,
   FolderLibraryIcon as FolderLibraryIconData,
   FolderOpenIcon as FolderOpenIconData,
   Image01Icon as Image01IconData,
@@ -112,6 +113,7 @@ export const File02Icon = createIcon(File02IconData)
 export const FileIcon = createIcon(FileIconData)
 export const FilePlus2Icon = createIcon(FileAddIcon)
 export const FileTextIcon = createIcon(FileTextIconData)
+export const FilterIcon = createIcon(FilterIconData)
 export const FolderLibraryIcon = createIcon(FolderLibraryIconData)
 export const FolderOpenIcon = createIcon(FolderOpenIconData)
 export const Image01Icon = createIcon(Image01IconData)
diff --git a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
index 93d7c136bc..7748811fc9 100644
--- a/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
+++ b/surfsense_local/frontend/src/features/dashboard/dashboard-page.tsx
@@ -255,7 +255,9 @@ function WorkspaceDashboard({
               }
               artifacts={
                 <ArtifactList
+                  workspaceId={workspace.id}
                   artifacts={studio.artifacts}
+                  formats={studio.formats}
                   isLoading={studio.isLoading}
                   onOpen={(artifactId) => {
                     openSources()
diff --git a/surfsense_local/frontend/src/features/studio/artifact-list.test.tsx b/surfsense_local/frontend/src/features/studio/artifact-list.test.tsx
index 456b8ef322..58dc9548a1 100644
--- a/surfsense_local/frontend/src/features/studio/artifact-list.test.tsx
+++ b/surfsense_local/frontend/src/features/studio/artifact-list.test.tsx
@@ -23,6 +23,7 @@ function renderList(props: Partial<Parameters<typeof ArtifactList>[0]> = {}) {
   return render(
     <TooltipProvider>
       <ArtifactList
+        workspaceId={1}
         artifacts={[artifact]}
         onOpen={vi.fn()}
         onDelete={vi.fn()}
@@ -196,4 +197,81 @@ describe("artifact list", () => {
       expect(screen.queryByRole("tooltip", { name: "boom" })).toBeNull()
     )
   })
+
+  describe("type filter", () => {
+    const podcast: Artifact = {
+      ...artifact,
+      id: 20,
+      format: "podcast",
+      title: "Episode one",
+    }
+    const infographic: Artifact = {
+      ...artifact,
+      id: 21,
+      format: "infographic",
+      title: "At a glance",
+    }
+
+    afterEach(() => localStorage.clear())
+
+    it("hides the filter control when there are no artifacts", () => {
+      renderList({ artifacts: [] })
+
+      expect(screen.queryByLabelText("Filter artifacts")).toBeNull()
+    })
+
+    it("lists each type once with a count and filters the list on check", async () => {
+      const user = userEvent.setup()
+      const podcastTwo = { ...podcast, id: 22, title: "Episode two" }
+      renderList({ artifacts: [artifact, podcast, podcastTwo, infographic] })
+
+      await user.click(screen.getByLabelText("Filter artifacts"))
+      expect(
+        screen.getByRole("menuitemcheckbox", { name: /podcast/i })
+      ).toBeTruthy()
+      expect(screen.getByText("(2)")).toBeTruthy()
+
+      await user.click(screen.getByRole("menuitemcheckbox", { name: /podcast/i }))
+      expect(screen.queryByRole("button", { name: "Weekly summary" })).toBeNull()
+      expect(screen.queryByRole("button", { name: "At a glance" })).toBeNull()
+      expect(screen.getByRole("button", { name: "Episode one" })).toBeTruthy()
+      expect(screen.getByRole("button", { name: "Episode two" })).toBeTruthy()
+    })
+
+    it("shows an empty state with a way to clear when a stored filter matches nothing here", async () => {
+      // The realistic way to land on zero matches: a filter saved while in a
+      // workspace with different artifact types (see the persistence test).
+      localStorage.setItem(
+        "surfsense:artifact-filter:1:v1",
+        JSON.stringify(["podcast"])
+      )
+      const user = userEvent.setup()
+      renderList({ workspaceId: 1, artifacts: [artifact] })
+
+      expect(screen.getByText("No artifacts match this filter")).toBeTruthy()
+      await user.click(screen.getByRole("button", { name: "Clear filter" }))
+      expect(screen.getByRole("button", { name: "Weekly summary" })).toBeTruthy()
+    })
+
+    it("persists the selected filter per workspace", async () => {
+      const user = userEvent.setup()
+      const { unmount } = renderList({
+        workspaceId: 1,
+        artifacts: [artifact, podcast],
+      })
+
+      await user.click(screen.getByLabelText("Filter artifacts"))
+      await user.click(screen.getByRole("menuitemcheckbox", { name: /podcast/i }))
+      unmount()
+
+      renderList({ workspaceId: 1, artifacts: [artifact, podcast] })
+      expect(screen.queryByRole("button", { name: "Weekly summary" })).toBeNull()
+      expect(screen.getByRole("button", { name: "Episode one" })).toBeTruthy()
+      cleanup()
+
+      renderList({ workspaceId: 2, artifacts: [artifact, podcast] })
+      expect(screen.getByRole("button", { name: "Weekly summary" })).toBeTruthy()
+      expect(screen.getByRole("button", { name: "Episode one" })).toBeTruthy()
+    })
+  })
 })
diff --git a/surfsense_local/frontend/src/features/studio/artifact-list.tsx b/surfsense_local/frontend/src/features/studio/artifact-list.tsx
index 264ea1bf77..dd51a47685 100644
--- a/surfsense_local/frontend/src/features/studio/artifact-list.tsx
+++ b/surfsense_local/frontend/src/features/studio/artifact-list.tsx
@@ -1,9 +1,10 @@
-import { useState } from "react"
+import { useMemo, useState } from "react"
 import {
   Alert02Icon,
   EllipsisIcon,
   FileIcon,
   FileTextIcon,
+  FilterIcon,
   Loader2Icon,
   RefreshCwIcon,
   Trash2Icon,
@@ -23,9 +24,12 @@ import {
 import { Button } from "@/components/ui/button"
 import {
   DropdownMenu,
+  DropdownMenuCheckboxItem,
   DropdownMenuContent,
   DropdownMenuGroup,
   DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu"
 import {
@@ -46,8 +50,34 @@ import {
 import { useModifierHeld } from "@/hooks/use-modifier-held"
 import { cn } from "@/lib/utils"
 
-import type { Artifact } from "./api"
-import { FORMAT_ICONS } from "./studio-panel"
+import type { Artifact, StudioFormat } from "./api"
+import { FORMAT_ICONS } from "./studio-formats"
+
+function artifactFilterKey(workspaceId: number) {
+  return `surfsense:artifact-filter:${workspaceId}:v1`
+}
+
+function readStoredFormats(workspaceId: number): string[] {
+  try {
+    const parsed: unknown = JSON.parse(
+      localStorage.getItem(artifactFilterKey(workspaceId)) ?? "[]"
+    )
+    return Array.isArray(parsed) ? parsed.filter((v) => typeof v === "string") : []
+  } catch {
+    return []
+  }
+}
+
+function writeStoredFormats(workspaceId: number, formats: string[]) {
+  try {
+    localStorage.setItem(
+      artifactFilterKey(workspaceId),
+      JSON.stringify(formats)
+    )
+  } catch {
+    // Private browsing and full disks throw.
+  }
+}
 
 function ArtifactRow({
   artifact,
@@ -187,32 +217,147 @@ function ArtifactRow({
 }
 
 export function ArtifactList({
+  workspaceId,
   artifacts,
+  formats = [],
   isLoading = false,
   onOpen,
   onDelete,
   onRetry,
 }: {
+  workspaceId: number
   artifacts: Artifact[]
+  formats?: StudioFormat[]
   isLoading?: boolean
   onOpen: (id: number) => void
   onDelete: (id: number) => void
   onRetry: (id: number) => void
 }) {
+  // The backend's format catalog is the single source of truth for labels;
+  // fall back to the raw key only for a format the catalog doesn't know yet.
+  const formatLabels = useMemo(
+    () => new Map(formats.map((format) => [format.key, format.label])),
+    [formats]
+  )
   const [deleteTarget, setDeleteTarget] = useState<Artifact | null>(null)
+  const [selectedFormats, setSelectedFormats] = useState<string[]>(() =>
+    readStoredFormats(workspaceId)
+  )
+  // The list stays mounted across workspace switches, so re-load the filter
+  // that workspace last saved instead of carrying the old one over. This is
+  // the "adjust state during render" idiom React recommends in place of an
+  // effect for resetting state when a prop changes.
+  const [renderedWorkspaceId, setRenderedWorkspaceId] = useState(workspaceId)
+  if (workspaceId !== renderedWorkspaceId) {
+    setRenderedWorkspaceId(workspaceId)
+    setSelectedFormats(readStoredFormats(workspaceId))
+  }
+
+  const availableFormats = useMemo(() => {
+    const counts = new Map<string, number>()
+    for (const artifact of artifacts) {
+      counts.set(artifact.format, (counts.get(artifact.format) ?? 0) + 1)
+    }
+    return [...counts.entries()]
+  }, [artifacts])
+
+  // Filtered directly against what's selected, not intersected with what's
+  // available — a filter saved in another workspace (e.g. "podcast") should
+  // correctly show zero results here rather than silently showing everything.
+  const visibleArtifacts = useMemo(() => {
+    if (selectedFormats.length === 0) return artifacts
+    const wanted = new Set(selectedFormats)
+    return artifacts.filter((artifact) => wanted.has(artifact.format))
+  }, [artifacts, selectedFormats])
+
+  function toggleFormat(format: string, checked: boolean) {
+    const next = checked
+      ? [...selectedFormats, format]
+      : selectedFormats.filter((candidate) => candidate !== format)
+    setSelectedFormats(next)
+    writeStoredFormats(workspaceId, next)
+  }
+
+  function clearFormats() {
+    setSelectedFormats([])
+    writeStoredFormats(workspaceId, [])
+  }
 
   return (
     <section
       className="flex h-full min-h-0 w-full min-w-0 flex-col"
       aria-labelledby="all-artifacts"
     >
-      <div className="mb-2 flex min-h-7 shrink-0 items-center">
+      <div className="mb-2 flex min-h-7 shrink-0 items-center justify-between gap-2">
         <h3
           id="all-artifacts"
           className="text-xs font-medium text-muted-foreground"
         >
           All generated artifacts
         </h3>
+        {availableFormats.length > 0 ? (
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                type="button"
+                size="icon-sm"
+                variant="ghost"
+                className={cn(
+                  "relative size-6 shrink-0 text-muted-foreground data-[state=open]:bg-accent",
+                  selectedFormats.length > 0 && "text-foreground"
+                )}
+                aria-label={
+                  selectedFormats.length > 0
+                    ? `Filter artifacts (${selectedFormats.length} active)`
+                    : "Filter artifacts"
+                }
+              >
+                <FilterIcon className="size-4" />
+                {selectedFormats.length > 0 ? (
+                  <span className="absolute top-0.5 right-0.5 size-1.5 rounded-full bg-primary" />
+                ) : null}
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent
+              align="end"
+              sideOffset={8}
+              className="w-52 select-none"
+            >
+              <DropdownMenuLabel>Filter by type</DropdownMenuLabel>
+              <DropdownMenuGroup>
+                {availableFormats.map(([format, count]) => {
+                  const FormatIcon = FORMAT_ICONS[format] ?? FileIcon
+                  return (
+                    <DropdownMenuCheckboxItem
+                      key={format}
+                      checked={selectedFormats.includes(format)}
+                      onCheckedChange={(checked) =>
+                        toggleFormat(format, checked === true)
+                      }
+                      onSelect={(event) => event.preventDefault()}
+                    >
+                      <FormatIcon className="size-4 text-muted-foreground" />
+                      <span className="flex-1">
+                        {formatLabels.get(format) ?? format}{" "}
+                        <span className="text-muted-foreground">
+                          ({count})
+                        </span>
+                      </span>
+                    </DropdownMenuCheckboxItem>
+                  )
+                })}
+              </DropdownMenuGroup>
+              {selectedFormats.length > 0 ? (
+                <>
+                  <DropdownMenuSeparator />
+                  <DropdownMenuItem onSelect={clearFormats}>
+                    Clear filter
+                  </DropdownMenuItem>
+                </>
+              ) : null}
+            </DropdownMenuContent>
+          </DropdownMenu>
+        ) : null}
       </div>
       <ScrollShadow className="min-h-0 flex-1" from="from-background">
         {isLoading ? (
@@ -229,9 +374,23 @@ export function ArtifactList({
               </EmptyDescription>
             </EmptyHeader>
           </Empty>
+        ) : visibleArtifacts.length === 0 ? (
+          <Empty className="min-h-0 border-0 px-2">
+            <EmptyHeader>
+              <EmptyMedia variant="icon">
+                <FilterIcon />
+              </EmptyMedia>
+              <EmptyTitle>No artifacts match this filter</EmptyTitle>
+              <EmptyDescription>
+                <Button type="button" variant="link" onClick={clearFormats}>
+                  Clear filter
+                </Button>
+              </EmptyDescription>
+            </EmptyHeader>
+          </Empty>
         ) : (
           <div className="flex flex-col gap-1">
-            {artifacts.map((artifact) => (
+            {visibleArtifacts.map((artifact) => (
               <ArtifactRow
                 key={artifact.id}
                 artifact={artifact}
diff --git a/surfsense_local/frontend/src/features/studio/studio-formats.ts b/surfsense_local/frontend/src/features/studio/studio-formats.ts
new file mode 100644
index 0000000000..5ed6f6403f
--- /dev/null
+++ b/surfsense_local/frontend/src/features/studio/studio-formats.ts
@@ -0,0 +1,36 @@
+import type { ComponentType } from "react"
+
+import {
+  AiSearchLinesIcon,
+  Cards01Icon,
+  ChartHistogramIcon,
+  File02Icon,
+  Image01Icon,
+  NetworkIcon,
+  Pdf01Icon,
+  PodcastIcon,
+  Presentation02Icon,
+  Quiz02Icon,
+  WebDesign01Icon,
+  Xls01Icon,
+} from "@/components/ui/icons"
+
+// Frontend-only concern: the backend's format catalog has no notion of an
+// icon, so this is the single place format keys map to one.
+export const FORMAT_ICONS: Record<
+  string,
+  ComponentType<{ className?: string }>
+> = {
+  summary: AiSearchLinesIcon,
+  docx: File02Icon,
+  pptx: Presentation02Icon,
+  xlsx: Xls01Icon,
+  html: WebDesign01Icon,
+  pdf: Pdf01Icon,
+  mindmap: NetworkIcon,
+  flashcards: Cards01Icon,
+  quiz: Quiz02Icon,
+  podcast: PodcastIcon,
+  image: Image01Icon,
+  infographic: ChartHistogramIcon,
+}
diff --git a/surfsense_local/frontend/src/features/studio/studio-panel.test.tsx b/surfsense_local/frontend/src/features/studio/studio-panel.test.tsx
index 6651031c99..1482591b5f 100644
--- a/surfsense_local/frontend/src/features/studio/studio-panel.test.tsx
+++ b/surfsense_local/frontend/src/features/studio/studio-panel.test.tsx
@@ -46,6 +46,7 @@ function StudioHarness({
         onGenerate={studio.create}
       />
       <ArtifactList
+        workspaceId={1}
         artifacts={studio.artifacts}
         isLoading={studio.isLoading}
         onOpen={vi.fn()}
diff --git a/surfsense_local/frontend/src/features/studio/studio-panel.tsx b/surfsense_local/frontend/src/features/studio/studio-panel.tsx
index e2de0c94b1..637e8840bc 100644
--- a/surfsense_local/frontend/src/features/studio/studio-panel.tsx
+++ b/surfsense_local/frontend/src/features/studio/studio-panel.tsx
@@ -1,21 +1,5 @@
-import { useState, type ComponentType } from "react"
-import {
-  AiSearchLinesIcon,
-  Cards01Icon,
-  ChartHistogramIcon,
-  CheckIcon,
-  File02Icon,
-  FileIcon,
-  Image01Icon,
-  NetworkIcon,
-  Pdf01Icon,
-  PodcastIcon,
-  Presentation02Icon,
-  Quiz02Icon,
-  SparklesIcon,
-  WebDesign01Icon,
-  Xls01Icon,
-} from "@/components/ui/icons"
+import { useState } from "react"
+import { CheckIcon, FileIcon, SparklesIcon } from "@/components/ui/icons"
 
 import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
 import { Button } from "@/components/ui/button"
@@ -38,6 +22,7 @@ import type { WorkspaceDocument } from "@/features/sources/api"
 import { cn } from "@/lib/utils"
 
 import type { StudioFormat, StudioJobCreate } from "./api"
+import { FORMAT_ICONS } from "./studio-formats"
 
 const FORMAT_HINTS: Record<string, string> = {
   summary: "Generate an AI summary based on your sources",
@@ -54,21 +39,6 @@ const FORMAT_HINTS: Record<string, string> = {
   infographic: "Generate an AI infographic based on your sources",
 }
 
-export const FORMAT_ICONS: Record<string, ComponentType<{ className?: string }>> = {
-  summary: AiSearchLinesIcon,
-  docx: File02Icon,
-  pptx: Presentation02Icon,
-  xlsx: Xls01Icon,
-  html: WebDesign01Icon,
-  pdf: Pdf01Icon,
-  mindmap: NetworkIcon,
-  flashcards: Cards01Icon,
-  quiz: Quiz02Icon,
-  podcast: PodcastIcon,
-  image: Image01Icon,
-  infographic: ChartHistogramIcon,
-}
-
 const STUDIO_CATALOG: StudioFormat[] = [
   { key: "summary", label: "Summary", requires_role: "generation", available: true, unavailable_reason: null },
   { key: "docx", label: "Document", requires_role: "generation", available: true, unavailable_reason: null },
@@ -325,7 +295,7 @@ export function StudioPanel({
           if (!open) setFormat(null)
         }}
       >
-        <DialogContent className="p-6 select-none sm:max-w-lg [&_[data-slot=dialog-close]]:top-3 [&_[data-slot=dialog-close]]:right-3">
+        <DialogContent className="p-6 select-none sm:max-w-lg **:data-[slot=dialog-close]:top-3 **:data-[slot=dialog-close]:right-3">
           {selectedFormat ? (
             <>
               <DialogHeader>