From 9d6d81871219906432e8b35260a8f5c3de6edbc6 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 1 Apr 2026 18:52:04 +0530
Subject: [PATCH 01/70] fix: add select-none class to TabBar

---
 surfsense_web/components/layout/ui/tabs/TabBar.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/surfsense_web/components/layout/ui/tabs/TabBar.tsx b/surfsense_web/components/layout/ui/tabs/TabBar.tsx
index 18e1ba141..8d0d986d3 100644
--- a/surfsense_web/components/layout/ui/tabs/TabBar.tsx
+++ b/surfsense_web/components/layout/ui/tabs/TabBar.tsx
@@ -72,7 +72,7 @@ export function TabBar({ onTabSwitch, onNewChat, rightActions, className }: TabB
 	if (tabs.length <= 1) return null;
 
 	return (
-		<div className={cn("mb-2 flex h-9 items-center shrink-0 px-1 gap-0.5", className)}>
+		<div className={cn("mb-2 flex h-9 items-center shrink-0 px-1 gap-0.5 select-none", className)}>
 			<div
 				ref={scrollRef}
 				className="flex h-full items-center flex-1 gap-0.5 overflow-x-auto overflow-y-hidden scrollbar-hide [scrollbar-width:none] [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden py-1"

From d7dd6db1b9e4c9dc1c9b75c0f53ae3920b7453de Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 1 Apr 2026 20:31:45 +0530
Subject: [PATCH 02/70] fix: improve document loading error handling and UI
 feedback for processing state

---
 surfsense_backend/app/routes/editor_routes.py | 11 ++++--
 .../components/DocumentsTableShell.tsx        |  5 +++
 .../components/documents/DocumentNode.tsx     |  4 +--
 .../components/documents/FolderTreeView.tsx   |  7 ++--
 .../components/editor-panel/editor-panel.tsx  | 22 +++++++++---
 .../layout/ui/tabs/DocumentTabContent.tsx     | 34 +++++++++++++++----
 .../new-chat/source-detail-panel.tsx          | 10 +++---
 7 files changed, 69 insertions(+), 24 deletions(-)

diff --git a/surfsense_backend/app/routes/editor_routes.py b/surfsense_backend/app/routes/editor_routes.py
index f54f18def..0fcbc475d 100644
--- a/surfsense_backend/app/routes/editor_routes.py
+++ b/surfsense_backend/app/routes/editor_routes.py
@@ -127,9 +127,16 @@ async def get_editor_content(
     chunks = sorted(document.chunks, key=lambda c: c.id)
 
     if not chunks:
+        doc_status = document.status or {}
+        state = doc_status.get("state", "ready") if isinstance(doc_status, dict) else "ready"
+        if state in ("pending", "processing"):
+            raise HTTPException(
+                status_code=409,
+                detail="This document is still being processed. Please wait a moment and try again.",
+            )
         raise HTTPException(
             status_code=400,
-            detail="This document has no content and cannot be edited. Please re-upload to enable editing.",
+            detail="This document has no viewable content yet. It may still be syncing. Try again in a few seconds, or re-upload if the issue persists.",
         )
 
     markdown_content = "\n\n".join(chunk.content for chunk in chunks)
@@ -137,7 +144,7 @@ async def get_editor_content(
     if not markdown_content.strip():
         raise HTTPException(
             status_code=400,
-            detail="This document has empty content and cannot be edited.",
+            detail="This document appears to be empty. Try re-uploading or editing it to add content.",
         )
 
     # Persist the lazy migration
diff --git a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx
index 92ced6e47..0758307f7 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx
@@ -748,6 +748,7 @@ export function DocumentsTableShell({
 																	onClick={() =>
 																		onOpenInTab ? onOpenInTab(doc) : handleViewDocument(doc)
 																	}
+																	disabled={isBeingProcessed}
 																>
 																	<Eye className="h-4 w-4" />
 																	Open
@@ -1020,6 +1021,10 @@ export function DocumentsTableShell({
 						<Button
 							variant="secondary"
 							className="justify-start gap-2"
+							disabled={
+								mobileActionDoc?.status?.state === "pending" ||
+								mobileActionDoc?.status?.state === "processing"
+							}
 							onClick={() => {
 								if (mobileActionDoc) handleViewDocument(mobileActionDoc);
 								setMobileActionDoc(null);
diff --git a/surfsense_web/components/documents/DocumentNode.tsx b/surfsense_web/components/documents/DocumentNode.tsx
index dd7731f22..691a6eb0d 100644
--- a/surfsense_web/components/documents/DocumentNode.tsx
+++ b/surfsense_web/components/documents/DocumentNode.tsx
@@ -219,7 +219,7 @@ export const DocumentNode = React.memo(function DocumentNode({
 							</Button>
 						</DropdownMenuTrigger>
 						<DropdownMenuContent align="end" className="w-40" onClick={(e) => e.stopPropagation()}>
-							<DropdownMenuItem onClick={() => onPreview(doc)}>
+							<DropdownMenuItem onClick={() => onPreview(doc)} disabled={isProcessing}>
 								<Eye className="mr-2 h-4 w-4" />
 								Open
 							</DropdownMenuItem>
@@ -259,7 +259,7 @@ export const DocumentNode = React.memo(function DocumentNode({
 
 			{contextMenuOpen && (
 				<ContextMenuContent className="w-40" onClick={(e) => e.stopPropagation()}>
-					<ContextMenuItem onClick={() => onPreview(doc)}>
+					<ContextMenuItem onClick={() => onPreview(doc)} disabled={isProcessing}>
 						<Eye className="mr-2 h-4 w-4" />
 						Open
 					</ContextMenuItem>
diff --git a/surfsense_web/components/documents/FolderTreeView.tsx b/surfsense_web/components/documents/FolderTreeView.tsx
index f63d5da5c..7695923e3 100644
--- a/surfsense_web/components/documents/FolderTreeView.tsx
+++ b/surfsense_web/components/documents/FolderTreeView.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAtom } from "jotai";
-import { CirclePlus } from "lucide-react";
+import { Search } from "lucide-react";
 import { useCallback, useMemo, useState } from "react";
 import { DndProvider } from "react-dnd";
 import { HTML5Backend } from "react-dnd-html5-backend";
@@ -250,8 +250,9 @@ export function FolderTreeView({
 	if (treeNodes.length === 0 && (activeTypes.length > 0 || searchQuery)) {
 		return (
 			<div className="flex flex-1 flex-col items-center justify-center gap-3 px-4 py-12 text-muted-foreground">
-				<CirclePlus className="h-10 w-10 rotate-45" />
-				<p className="text-sm">No matching documents</p>
+				<Search className="h-10 w-10" />
+				<p className="text-sm text-muted-foreground">No matching documents</p>
+				<p className="text-xs text-muted-foreground/70 mt-1">Try a different search term</p>
 			</div>
 		);
 	}
diff --git a/surfsense_web/components/editor-panel/editor-panel.tsx b/surfsense_web/components/editor-panel/editor-panel.tsx
index 3ea36f800..7496e6aec 100644
--- a/surfsense_web/components/editor-panel/editor-panel.tsx
+++ b/surfsense_web/components/editor-panel/editor-panel.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAtomValue, useSetAtom } from "jotai";
-import { AlertCircle, XIcon } from "lucide-react";
+import { FileQuestionMark, RefreshCw, XIcon } from "lucide-react";
 import dynamic from "next/dynamic";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { toast } from "sonner";
@@ -200,10 +200,22 @@ export function EditorPanelContent({
 					<EditorPanelSkeleton />
 				) : error || !editorDoc ? (
 					<div className="flex flex-1 flex-col items-center justify-center gap-3 p-6 text-center">
-						<AlertCircle className="size-8 text-destructive" />
-						<div>
-							<p className="font-medium text-foreground">Failed to load document</p>
-							<p className="text-sm text-red-500 mt-1">{error || "An unknown error occurred"}</p>
+						{error?.toLowerCase().includes("still being processed") ? (
+							<div className="rounded-full bg-muted/50 p-3">
+								<RefreshCw className="size-6 text-muted-foreground animate-spin" />
+							</div>
+						) : (
+							<div className="rounded-full bg-muted/50 p-3">
+								<FileQuestionMark className="size-6 text-muted-foreground" />
+							</div>
+						)}
+						<div className="space-y-1 max-w-xs">
+							<p className="font-medium text-foreground">
+								{error?.toLowerCase().includes("still being processed")
+									? "Document is processing"
+									: "Document unavailable"}
+							</p>
+							<p className="text-sm text-muted-foreground">{error || "An unknown error occurred"}</p>
 						</div>
 					</div>
 				) : isEditableType ? (
diff --git a/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx b/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx
index ac279cd4d..849bdbea5 100644
--- a/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx
+++ b/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { AlertCircle, Pencil } from "lucide-react";
+import { FileQuestionMark, PenLine, RefreshCw } from "lucide-react";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { toast } from "sonner";
 import { PlateEditor } from "@/components/editor/plate-editor";
@@ -160,15 +160,35 @@ export function DocumentTabContent({ documentId, searchSpaceId, title }: Documen
 	if (isLoading) return <DocumentSkeleton />;
 
 	if (error || !doc) {
+		const isProcessing = error?.toLowerCase().includes("still being processed");
 		return (
-			<div className="flex flex-1 flex-col items-center justify-center gap-3 p-6 text-center">
-				<AlertCircle className="size-10 text-destructive" />
-				<div>
-					<p className="font-medium text-foreground text-lg">Failed to load document</p>
-					<p className="text-sm text-muted-foreground mt-1">
+			<div className="flex flex-1 flex-col items-center justify-center gap-4 p-8 text-center">
+				<div className="rounded-full bg-muted/50 p-4">
+					{isProcessing ? (
+						<RefreshCw className="size-8 text-muted-foreground animate-spin" />
+					) : (
+						<FileQuestionMark className="size-8 text-muted-foreground" />
+					)}
+				</div>
+				<div className="space-y-1.5 max-w-sm">
+					<p className="font-semibold text-foreground text-lg">
+						{isProcessing ? "Document is processing" : "Document unavailable"}
+					</p>
+					<p className="text-sm text-muted-foreground">
 						{error || "An unknown error occurred"}
 					</p>
 				</div>
+				{!isProcessing && (
+					<Button
+						variant="outline"
+						size="sm"
+						className="mt-1 gap-1.5"
+						onClick={() => window.location.reload()}
+					>
+						<RefreshCw className="size-3.5" />
+						Retry
+					</Button>
+				)}
 			</div>
 		);
 	}
@@ -229,7 +249,7 @@ export function DocumentTabContent({ documentId, searchSpaceId, title }: Documen
 						onClick={() => setIsEditing(true)}
 						className="gap-1.5"
 					>
-						<Pencil className="size-3.5" />
+						<PenLine className="size-3.5" />
 						Edit
 					</Button>
 				)}
diff --git a/surfsense_web/components/new-chat/source-detail-panel.tsx b/surfsense_web/components/new-chat/source-detail-panel.tsx
index b02b2e217..9c1167efe 100644
--- a/surfsense_web/components/new-chat/source-detail-panel.tsx
+++ b/surfsense_web/components/new-chat/source-detail-panel.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useQuery } from "@tanstack/react-query";
-import { BookOpen, ChevronDown, ExternalLink, FileText, Hash, Sparkles, X } from "lucide-react";
+import { BookOpen, ChevronDown, ExternalLink, FileQuestionMark, FileText, Hash, Sparkles, X } from "lucide-react";
 import { AnimatePresence, motion, useReducedMotion } from "motion/react";
 import { useTranslations } from "next-intl";
 import type React from "react";
@@ -392,12 +392,12 @@ export function SourceDetailPanel({
 									animate={{ opacity: 1, scale: 1 }}
 									className="flex flex-col items-center gap-4 text-center px-6"
 								>
-									<div className="w-20 h-20 rounded-full bg-destructive/10 flex items-center justify-center">
-										<X className="h-10 w-10 text-destructive" />
+									<div className="w-20 h-20 rounded-full bg-muted/50 flex items-center justify-center">
+										<FileQuestionMark className="h-10 w-10 text-muted-foreground" />
 									</div>
 									<div>
-										<p className="font-semibold text-destructive text-lg">
-											Failed to load document
+										<p className="font-semibold text-foreground text-lg">
+											Document unavailable
 										</p>
 										<p className="text-sm text-muted-foreground mt-2 max-w-md">
 											{documentByChunkFetchingError.message ||

From 5c11a15fb6534c55e3e50e49caac4e4ee3703cec Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 1 Apr 2026 20:51:55 +0530
Subject: [PATCH 03/70] refactor: update UI components by removing unused
 imports and adjusting loading states

---
 .../components/CommunityPromptsContent.tsx    |  2 +-
 .../components/PromptsContent.tsx             |  6 ++--
 .../components/editor-panel/editor-panel.tsx  | 29 +++++++++----------
 .../layout/ui/right-panel/RightPanel.tsx      |  2 +-
 .../settings/image-model-manager.tsx          |  3 +-
 .../settings/model-config-manager.tsx         |  2 --
 6 files changed, 20 insertions(+), 24 deletions(-)

diff --git a/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/CommunityPromptsContent.tsx b/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/CommunityPromptsContent.tsx
index 4bcdcba7e..239832b2d 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/CommunityPromptsContent.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/CommunityPromptsContent.tsx
@@ -60,7 +60,7 @@ export function CommunityPromptsContent() {
 
 			{list.length === 0 && (
 				<div className="rounded-lg border border-dashed border-border/60 p-8 text-center">
-					<Globe className="mx-auto size-8 text-muted-foreground/40" />
+					<Globe className="mx-auto size-8 text-muted-foreground" />
 					<p className="mt-2 text-sm text-muted-foreground">No community prompts yet</p>
 					<p className="text-xs text-muted-foreground/60">
 						Share your own prompts from the My Prompts tab
diff --git a/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/PromptsContent.tsx b/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/PromptsContent.tsx
index 522d71e59..39362d244 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/PromptsContent.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/PromptsContent.tsx
@@ -1,7 +1,8 @@
 "use client";
 
 import { useAtomValue } from "jotai";
-import { AlertTriangle, Globe, Lock, PenLine, Plus, Sparkles, Trash2 } from "lucide-react";
+import { AlertTriangle, Globe, Lock, PenLine, Sparkles, Trash2 } from "lucide-react";
+import { ShortcutKbd } from "@/components/ui/shortcut-kbd";
 import { useCallback, useState } from "react";
 import { toast } from "sonner";
 import {
@@ -145,7 +146,7 @@ export function PromptsContent() {
 			<div className="flex items-center justify-between">
 				<p className="text-sm text-muted-foreground">
 					Create prompt templates triggered with{" "}
-					<kbd className="rounded border bg-muted px-1.5 py-0.5 text-xs font-mono">/</kbd> in the
+					<ShortcutKbd keys={["/"]} className="ml-0" /> in the
 					chat composer.
 				</p>
 				{!showForm && (
@@ -158,7 +159,6 @@ export function PromptsContent() {
 						}}
 						className="shrink-0 gap-1.5"
 					>
-						<Plus className="size-3.5" />
 						New
 					</Button>
 				)}
diff --git a/surfsense_web/components/editor-panel/editor-panel.tsx b/surfsense_web/components/editor-panel/editor-panel.tsx
index 7496e6aec..802a5ffc3 100644
--- a/surfsense_web/components/editor-panel/editor-panel.tsx
+++ b/surfsense_web/components/editor-panel/editor-panel.tsx
@@ -9,24 +9,9 @@ import { closeEditorPanelAtom, editorPanelAtom } from "@/atoms/editor/editor-pan
 import { MarkdownViewer } from "@/components/markdown-viewer";
 import { Button } from "@/components/ui/button";
 import { Drawer, DrawerContent, DrawerHandle, DrawerTitle } from "@/components/ui/drawer";
-import { Skeleton } from "@/components/ui/skeleton";
 import { useMediaQuery } from "@/hooks/use-media-query";
 import { authenticatedFetch, getBearerToken, redirectToLogin } from "@/lib/auth-utils";
 
-const PlateEditor = dynamic(
-	() => import("@/components/editor/plate-editor").then((m) => ({ default: m.PlateEditor })),
-	{ ssr: false, loading: () => <Skeleton className="h-64 w-full" /> }
-);
-
-interface EditorContent {
-	document_id: number;
-	title: string;
-	document_type?: string;
-	source_markdown: string;
-}
-
-const EDITABLE_DOCUMENT_TYPES = new Set(["FILE", "NOTE"]);
-
 function EditorPanelSkeleton() {
 	return (
 		<div className="space-y-6 p-6">
@@ -47,6 +32,20 @@ function EditorPanelSkeleton() {
 	);
 }
 
+const PlateEditor = dynamic(
+	() => import("@/components/editor/plate-editor").then((m) => ({ default: m.PlateEditor })),
+	{ ssr: false, loading: () => null }
+);
+
+interface EditorContent {
+	document_id: number;
+	title: string;
+	document_type?: string;
+	source_markdown: string;
+}
+
+const EDITABLE_DOCUMENT_TYPES = new Set(["FILE", "NOTE"]);
+
 export function EditorPanelContent({
 	documentId,
 	searchSpaceId,
diff --git a/surfsense_web/components/layout/ui/right-panel/RightPanel.tsx b/surfsense_web/components/layout/ui/right-panel/RightPanel.tsx
index ac2f65065..717f5a459 100644
--- a/surfsense_web/components/layout/ui/right-panel/RightPanel.tsx
+++ b/surfsense_web/components/layout/ui/right-panel/RightPanel.tsx
@@ -19,7 +19,7 @@ const EditorPanelContent = dynamic(
 		import("@/components/editor-panel/editor-panel").then((m) => ({
 			default: m.EditorPanelContent,
 		})),
-	{ ssr: false, loading: () => <Skeleton className="h-96 w-full" /> }
+	{ ssr: false, loading: () => null }
 );
 
 const HitlEditPanelContent = dynamic(
diff --git a/surfsense_web/components/settings/image-model-manager.tsx b/surfsense_web/components/settings/image-model-manager.tsx
index 8f08b7db3..0c45af7d4 100644
--- a/surfsense_web/components/settings/image-model-manager.tsx
+++ b/surfsense_web/components/settings/image-model-manager.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAtomValue } from "jotai";
-import { AlertCircle, Edit3, Info, Plus, RefreshCw, Trash2, Wand2 } from "lucide-react";
+import { AlertCircle, Edit3, Info, RefreshCw, Trash2, Wand2 } from "lucide-react";
 import { useMemo, useState } from "react";
 import { deleteImageGenConfigMutationAtom } from "@/atoms/image-gen-config/image-gen-config-mutation.atoms";
 import {
@@ -257,7 +257,6 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 										size="lg"
 										className="gap-2 text-xs md:text-sm h-9 md:h-10"
 									>
-										<Plus className="h-3 w-3 md:h-4 md:w-4" />
 										Add First Image Model
 									</Button>
 								)}
diff --git a/surfsense_web/components/settings/model-config-manager.tsx b/surfsense_web/components/settings/model-config-manager.tsx
index 046288a96..50d2ab5b7 100644
--- a/surfsense_web/components/settings/model-config-manager.tsx
+++ b/surfsense_web/components/settings/model-config-manager.tsx
@@ -7,7 +7,6 @@ import {
 	FileText,
 	Info,
 	MessageSquareQuote,
-	Plus,
 	RefreshCw,
 	Trash2,
 	Wand2,
@@ -270,7 +269,6 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 											size="lg"
 											className="gap-2 text-xs md:text-sm h-9 md:h-10"
 										>
-											<Plus className="h-3 w-3 md:h-4 md:w-4" />
 											Create First Configuration
 										</Button>
 									)}

From 33e7aeef9d275a49ad0b7e74a46244b42d4ef547 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 1 Apr 2026 21:00:52 +0530
Subject: [PATCH 04/70] style: enhance input field focus styles and transition
 effects in login and registration forms

---
 .../app/(home)/login/LocalLoginForm.tsx       |  20 +--
 surfsense_web/app/(home)/register/page.tsx    | 142 +++++++++---------
 2 files changed, 81 insertions(+), 81 deletions(-)

diff --git a/surfsense_web/app/(home)/login/LocalLoginForm.tsx b/surfsense_web/app/(home)/login/LocalLoginForm.tsx
index ee3b47683..1ebbf46b6 100644
--- a/surfsense_web/app/(home)/login/LocalLoginForm.tsx
+++ b/surfsense_web/app/(home)/login/LocalLoginForm.tsx
@@ -160,11 +160,11 @@ export function LocalLoginForm() {
 						placeholder="you@example.com"
 						value={username}
 						onChange={(e) => setUsername(e.target.value)}
-						className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 bg-background text-foreground transition-all ${
-							error.title
-								? "border-destructive focus:border-destructive focus:ring-destructive"
-								: "border-border focus:border-primary focus:ring-primary"
-						}`}
+					className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+						error.title
+							? "border-destructive focus:border-destructive focus:ring-destructive/40"
+							: "border-border focus:border-primary focus:ring-primary/40"
+					}`}
 						disabled={isLoggingIn}
 					/>
 				</div>
@@ -181,11 +181,11 @@ export function LocalLoginForm() {
 							placeholder="Enter your password"
 							value={password}
 							onChange={(e) => setPassword(e.target.value)}
-							className={`mt-1 block w-full rounded-md border pr-10 px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 bg-background text-foreground transition-all ${
-								error.title
-									? "border-destructive focus:border-destructive focus:ring-destructive"
-									: "border-border focus:border-primary focus:ring-primary"
-							}`}
+						className={`mt-1 block w-full rounded-md border pr-10 px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+							error.title
+								? "border-destructive focus:border-destructive focus:ring-destructive/40"
+								: "border-border focus:border-primary focus:ring-primary/40"
+						}`}
 							disabled={isLoggingIn}
 						/>
 						<button
diff --git a/surfsense_web/app/(home)/register/page.tsx b/surfsense_web/app/(home)/register/page.tsx
index b9200c68f..3161da4a7 100644
--- a/surfsense_web/app/(home)/register/page.tsx
+++ b/surfsense_web/app/(home)/register/page.tsx
@@ -229,78 +229,78 @@ export default function RegisterPage() {
 						</AnimatePresence>
 
 						<div>
-							<label
-								htmlFor="email"
-								className="block text-sm font-medium text-gray-700 dark:text-gray-300"
-							>
-								{t("email")}
-							</label>
-							<input
-								id="email"
-								type="email"
-								required
-								placeholder="you@example.com"
-								value={email}
-								onChange={(e) => setEmail(e.target.value)}
-								className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 dark:bg-gray-800 dark:text-white transition-all ${
-									error.title
-										? "border-red-300 focus:border-red-500 focus:ring-red-500 dark:border-red-700"
-										: "border-gray-300 focus:border-blue-500 focus:ring-blue-500 dark:border-gray-700"
-								}`}
-								disabled={isRegistering}
-							/>
-						</div>
+						<label
+							htmlFor="email"
+							className="block text-sm font-medium text-foreground"
+						>
+							{t("email")}
+						</label>
+						<input
+							id="email"
+							type="email"
+							required
+							placeholder="you@example.com"
+							value={email}
+							onChange={(e) => setEmail(e.target.value)}
+						className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+							error.title
+								? "border-destructive focus:border-destructive focus:ring-destructive/40"
+								: "border-border focus:border-primary focus:ring-primary/40"
+						}`}
+						disabled={isRegistering}
+					/>
+					</div>
 
-						<div>
-							<label
-								htmlFor="password"
-								className="block text-sm font-medium text-gray-700 dark:text-gray-300"
-							>
-								{t("password")}
-							</label>
-							<input
-								id="password"
-								type="password"
-								required
-								placeholder="Enter your password"
-								value={password}
-								onChange={(e) => setPassword(e.target.value)}
-								className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 dark:bg-gray-800 dark:text-white transition-all ${
-									error.title
-										? "border-red-300 focus:border-red-500 focus:ring-red-500 dark:border-red-700"
-										: "border-gray-300 focus:border-blue-500 focus:ring-blue-500 dark:border-gray-700"
-								}`}
-								disabled={isRegistering}
-							/>
-						</div>
+					<div>
+						<label
+							htmlFor="password"
+							className="block text-sm font-medium text-foreground"
+						>
+							{t("password")}
+						</label>
+						<input
+							id="password"
+							type="password"
+							required
+							placeholder="Enter your password"
+							value={password}
+							onChange={(e) => setPassword(e.target.value)}
+							className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+								error.title
+									? "border-destructive focus:border-destructive focus:ring-destructive/40"
+									: "border-border focus:border-primary focus:ring-primary/40"
+							}`}
+							disabled={isRegistering}
+						/>
+					</div>
 
-						<div>
-							<label
-								htmlFor="confirmPassword"
-								className="block text-sm font-medium text-gray-700 dark:text-gray-300"
-							>
-								{t("confirm_password")}
-							</label>
-							<input
-								id="confirmPassword"
-								type="password"
-								required
-								placeholder="Confirm your password"
-								value={confirmPassword}
-								onChange={(e) => setConfirmPassword(e.target.value)}
-								className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-2 focus:ring-offset-2 dark:bg-gray-800 dark:text-white transition-all ${
-									error.title
-										? "border-red-300 focus:border-red-500 focus:ring-red-500 dark:border-red-700"
-										: "border-gray-300 focus:border-blue-500 focus:ring-blue-500 dark:border-gray-700"
-								}`}
-								disabled={isRegistering}
-							/>
+					<div>
+						<label
+							htmlFor="confirmPassword"
+							className="block text-sm font-medium text-foreground"
+						>
+							{t("confirm_password")}
+						</label>
+						<input
+							id="confirmPassword"
+							type="password"
+							required
+							placeholder="Confirm your password"
+							value={confirmPassword}
+							onChange={(e) => setConfirmPassword(e.target.value)}
+							className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+								error.title
+									? "border-destructive focus:border-destructive focus:ring-destructive/40"
+									: "border-border focus:border-primary focus:ring-primary/40"
+							}`}
+							disabled={isRegistering}
+						/>
 						</div>
 
 						<button
 							type="submit"
 							disabled={isRegistering}
-							className="relative w-full rounded-md bg-blue-600 px-4 py-1.5 md:py-2 text-white shadow-sm hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 transition-all text-sm md:text-base flex items-center justify-center gap-2"
+							className="relative w-full rounded-md bg-primary px-4 py-1.5 md:py-2 text-primary-foreground shadow-sm hover:bg-primary/90 focus:outline-none focus:ring-1 focus:ring-primary/40 disabled:cursor-not-allowed disabled:opacity-50 transition-all text-sm md:text-base flex items-center justify-center gap-2"
 						>
 							<span className={isRegistering ? "invisible" : ""}>{t("register")}</span>
 							{isRegistering && (
@@ -312,12 +312,12 @@ export default function RegisterPage() {
 					</form>
 
 					<div className="mt-4 text-center text-sm">
-						<p className="text-gray-600 dark:text-gray-400">
-							{t("already_have_account")}{" "}
-							<Link
-								href="/login"
-								className="font-medium text-blue-600 hover:text-blue-500 dark:text-blue-400"
-							>
+					<p className="text-muted-foreground">
+						{t("already_have_account")}{" "}
+						<Link
+							href="/login"
+							className="font-medium text-primary hover:text-primary/90"
+						>
 								{t("sign_in")}
 							</Link>
 						</p>

From 917ec444bb5b5b07b5dbffdb446eb35561984f1f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Wed, 1 Apr 2026 23:00:45 +0530
Subject: [PATCH 05/70] style: add overscroll-none class to ComposerAction
 component

---
 surfsense_web/components/assistant-ui/thread.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 2cf0393da..53770ef83 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -1063,7 +1063,7 @@ const ComposerAction: FC<ComposerActionProps> = ({ isBlockedByOtherUser = false
 						>
 							<div className="sr-only">Manage Tools</div>
 							<div
-								className="max-h-48 sm:max-h-64 overflow-y-auto py-0.5 sm:py-1"
+								className="max-h-48 sm:max-h-64 overflow-y-auto overscroll-none py-0.5 sm:py-1"
 								onScroll={handleToolsScroll}
 								style={{
 									maskImage: `linear-gradient(to bottom, ${toolsScrollPos === "top" ? "black" : "transparent"}, black 16px, black calc(100% - 16px), ${toolsScrollPos === "bottom" ? "black" : "transparent"})`,

From 1f8f71b542e5bb8d96c8bea7b1122f41240e076e Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 00:22:10 +0530
Subject: [PATCH 06/70] chore: add chokidar dependency for file watching

---
 surfsense_desktop/package.json   |  1 +
 surfsense_desktop/pnpm-lock.yaml | 17 +++++++++++++++++
 2 files changed, 18 insertions(+)

diff --git a/surfsense_desktop/package.json b/surfsense_desktop/package.json
index bd0cc67ab..5bbd50514 100644
--- a/surfsense_desktop/package.json
+++ b/surfsense_desktop/package.json
@@ -27,6 +27,7 @@
     "wait-on": "^9.0.4"
   },
   "dependencies": {
+    "chokidar": "^5.0.0",
     "electron-updater": "^6.8.3",
     "get-port-please": "^3.2.0"
   }
diff --git a/surfsense_desktop/pnpm-lock.yaml b/surfsense_desktop/pnpm-lock.yaml
index ea65be0bb..1533803fb 100644
--- a/surfsense_desktop/pnpm-lock.yaml
+++ b/surfsense_desktop/pnpm-lock.yaml
@@ -8,6 +8,9 @@ importers:
 
   .:
     dependencies:
+      chokidar:
+        specifier: ^5.0.0
+        version: 5.0.0
       electron-updater:
         specifier: ^6.8.3
         version: 6.8.3
@@ -477,6 +480,10 @@ packages:
     resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
     engines: {node: '>=10'}
 
+  chokidar@5.0.0:
+    resolution: {integrity: sha512-TQMmc3w+5AxjpL8iIiwebF73dRDF4fBIieAqGn9RGCWaEVwQ6Fb2cGe31Yns0RRIzii5goJ1Y7xbMwo1TxMplw==}
+    engines: {node: '>= 20.19.0'}
+
   chownr@3.0.0:
     resolution: {integrity: sha512-+IxzY9BZOQd/XuYPRmrvEVjF/nqj5kgT4kEq7VofrDoM1MxoRjEWkrCC3EtLi59TVawxTAn+orJwFQcrqEN1+g==}
     engines: {node: '>=18'}
@@ -1222,6 +1229,10 @@ packages:
     resolution: {integrity: sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==}
     engines: {node: '>= 6'}
 
+  readdirp@5.0.0:
+    resolution: {integrity: sha512-9u/XQ1pvrQtYyMpZe7DXKv2p5CNvyVwzUB6uhLAnQwHMSgKMBR62lc7AHljaeteeHXn11XTAaLLUVZYVZyuRBQ==}
+    engines: {node: '>= 20.19.0'}
+
   require-directory@2.1.1:
     resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
     engines: {node: '>=0.10.0'}
@@ -2019,6 +2030,10 @@ snapshots:
       ansi-styles: 4.3.0
       supports-color: 7.2.0
 
+  chokidar@5.0.0:
+    dependencies:
+      readdirp: 5.0.0
+
   chownr@3.0.0: {}
 
   chromium-pickle-js@0.2.0: {}
@@ -2863,6 +2878,8 @@ snapshots:
       string_decoder: 1.3.0
       util-deprecate: 1.0.2
 
+  readdirp@5.0.0: {}
+
   require-directory@2.1.1: {}
 
   resedit@1.7.2:

From 2df9708df9e5b3c9fafca48144a43b96ffe160b8 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 09:16:07 +0530
Subject: [PATCH 07/70] style: update alert components and empty state UI

---
 .../assistant-ui/connector-popup.tsx          |  6 ++--
 .../assistant-ui/document-upload-popup.tsx    |  6 ++--
 .../public-chat-snapshots-empty-state.tsx     |  7 ++---
 .../settings/image-model-manager.tsx          | 18 ++----------
 .../settings/model-config-manager.tsx         | 28 +++++--------------
 5 files changed, 18 insertions(+), 47 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/connector-popup.tsx b/surfsense_web/components/assistant-ui/connector-popup.tsx
index d1f6dd31f..b31b7cbd1 100644
--- a/surfsense_web/components/assistant-ui/connector-popup.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup.tsx
@@ -376,14 +376,14 @@ export const ConnectorIndicator = forwardRef<ConnectorIndicatorHandle, Connector
 									<div className="px-4 sm:px-12 py-4 sm:py-8 pb-12 sm:pb-16">
 										{/* LLM Configuration Warning */}
 										{!llmConfigLoading && !hasDocumentSummaryLLM && (
-											<Alert variant="destructive" className="mb-6">
+											<Alert variant="destructive" className="mb-6 bg-muted/50 rounded-xl border-destructive/30">
 												<AlertTriangle className="h-4 w-4" />
 												<AlertTitle>LLM Configuration Required</AlertTitle>
 												<AlertDescription className="mt-2">
 													<p className="mb-3">
 														{isAutoMode && !hasGlobalConfigs
-															? "Auto mode is selected but no global LLM configurations are available. Please configure a custom LLM in Settings to process and summarize documents from your connected sources."
-															: "You need to configure a Document Summary LLM before adding connectors. This LLM is used to process and summarize documents from your connected sources."}
+															? "Auto mode requires a global LLM configuration. Please add one in Settings"
+															: "A Document Summary LLM is required to process uploads, configure one in Settings"}
 													</p>
 													<Button
 														size="sm"
diff --git a/surfsense_web/components/assistant-ui/document-upload-popup.tsx b/surfsense_web/components/assistant-ui/document-upload-popup.tsx
index c34890dff..06b0d38e7 100644
--- a/surfsense_web/components/assistant-ui/document-upload-popup.tsx
+++ b/surfsense_web/components/assistant-ui/document-upload-popup.tsx
@@ -149,14 +149,14 @@ const DocumentUploadPopupContent: FC<{
 					{/* Content */}
 					<div className="px-4 sm:px-12 pb-4 sm:pb-16">
 						{!isLoading && !hasDocumentSummaryLLM ? (
-							<Alert variant="destructive" className="mb-4">
+							<Alert variant="destructive" className="mb-4 bg-muted/50 rounded-xl border-destructive/30">
 								<AlertTriangle className="h-4 w-4" />
 								<AlertTitle>LLM Configuration Required</AlertTitle>
 								<AlertDescription className="mt-2">
 									<p className="mb-3">
 										{isAutoMode && !hasGlobalConfigs
-											? "Auto mode is selected but no global LLM configurations are available. Please configure a custom LLM in Settings to process and summarize your uploaded documents."
-											: "You need to configure a Document Summary LLM before uploading files. This LLM is used to process and summarize your uploaded documents."}
+											? "Auto mode requires a global LLM configuration. Please add one in Settings"
+											: "A Document Summary LLM is required to process uploads, configure one in Settings"}
 									</p>
 									<Button
 										size="sm"
diff --git a/surfsense_web/components/public-chat-snapshots/public-chat-snapshots-empty-state.tsx b/surfsense_web/components/public-chat-snapshots/public-chat-snapshots-empty-state.tsx
index 4a4a57770..4e8ec5bb6 100644
--- a/surfsense_web/components/public-chat-snapshots/public-chat-snapshots-empty-state.tsx
+++ b/surfsense_web/components/public-chat-snapshots/public-chat-snapshots-empty-state.tsx
@@ -11,11 +11,8 @@ export function PublicChatSnapshotsEmptyState({
 }: PublicChatSnapshotsEmptyStateProps) {
 	return (
 		<div className="flex flex-col items-center justify-center py-12 text-center">
-			<div className="rounded-full bg-muted p-3 mb-4">
-				<Link2Off className="h-6 w-6 text-muted-foreground" />
-			</div>
-			<h3 className="text-sm font-medium text-foreground mb-1">{title}</h3>
-			<p className="text-xs text-muted-foreground max-w-sm">{description}</p>
+			<h3 className="text-sm md:text-base font-semibold mb-2">{title}</h3>
+			<p className="text-[11px] md:text-xs text-muted-foreground max-w-sm">{description}</p>
 		</div>
 	);
 }
diff --git a/surfsense_web/components/settings/image-model-manager.tsx b/surfsense_web/components/settings/image-model-manager.tsx
index 0c45af7d4..55128dc59 100644
--- a/surfsense_web/components/settings/image-model-manager.tsx
+++ b/surfsense_web/components/settings/image-model-manager.tsx
@@ -240,26 +240,14 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 			{!isLoading && (
 				<div className="space-y-4 md:space-y-6">
 					{(userConfigs?.length ?? 0) === 0 ? (
-						<Card className="border-dashed border-2 border-muted-foreground/25">
+						<Card className="border-0 bg-transparent shadow-none">
 							<CardContent className="flex flex-col items-center justify-center py-10 md:py-16 text-center">
-								<div className="rounded-full bg-gradient-to-br from-teal-500/10 to-cyan-500/10 p-4 md:p-6 mb-4">
-									<Wand2 className="h-8 w-8 md:h-12 md:w-12 text-teal-600 dark:text-teal-400" />
-								</div>
-								<h3 className="text-lg font-semibold mb-2">No Image Models Yet</h3>
-								<p className="text-xs md:text-sm text-muted-foreground max-w-sm mb-4">
+								<h3 className="text-sm md:text-base font-semibold mb-2">No Image Models Yet</h3>
+								<p className="text-[11px] md:text-xs text-muted-foreground max-w-sm mb-4">
 									{canCreate
 										? "Add your own image generation model (DALL-E 3, GPT Image 1, etc.)"
 										: "No image models have been added to this space yet. Contact a space owner to add one."}
 								</p>
-								{canCreate && (
-									<Button
-										onClick={openNewDialog}
-										size="lg"
-										className="gap-2 text-xs md:text-sm h-9 md:h-10"
-									>
-										Add First Image Model
-									</Button>
-								)}
 							</CardContent>
 						</Card>
 					) : (
diff --git a/surfsense_web/components/settings/model-config-manager.tsx b/surfsense_web/components/settings/model-config-manager.tsx
index 50d2ab5b7..837060c70 100644
--- a/surfsense_web/components/settings/model-config-manager.tsx
+++ b/surfsense_web/components/settings/model-config-manager.tsx
@@ -250,28 +250,14 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 				<div className="space-y-4">
 					{configs?.length === 0 ? (
 						<div>
-							<Card className="border-dashed border-2 border-muted-foreground/25">
+							<Card className="border-0 bg-transparent shadow-none">
 								<CardContent className="flex flex-col items-center justify-center py-10 md:py-16 text-center">
-									<div className="rounded-full bg-gradient-to-br from-violet-500/10 to-purple-500/10 p-4 md:p-6 mb-4 md:mb-6">
-										<Wand2 className="h-8 w-8 md:h-12 md:w-12 text-violet-600 dark:text-violet-400" />
-									</div>
-									<div className="space-y-2 mb-4 md:mb-6">
-										<h3 className="text-lg md:text-xl font-semibold">No Configurations Yet</h3>
-										<p className="text-xs md:text-sm text-muted-foreground max-w-sm">
-											{canCreate
-												? "Create your first AI configuration to customize how your agent responds"
-												: "No AI configurations have been added to this space yet. Contact a space owner to add one."}
-										</p>
-									</div>
-									{canCreate && (
-										<Button
-											onClick={openNewDialog}
-											size="lg"
-											className="gap-2 text-xs md:text-sm h-9 md:h-10"
-										>
-											Create First Configuration
-										</Button>
-									)}
+									<h3 className="text-sm md:text-base font-semibold mb-2">No LLM Models Yet</h3>
+									<p className="text-[11px] md:text-xs text-muted-foreground max-w-sm mb-4">
+										{canCreate
+											? "Add your first LLM model to power document summarization, chat, and other agent capabilities"
+											: "No LLM models have been added to this space yet. Contact a space owner to add one"}
+									</p>
 								</CardContent>
 							</Card>
 						</div>

From 407175ffae46a23d775bcba9c35fdfb465766ba0 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 09:26:16 +0530
Subject: [PATCH 08/70] style: replace loading indicators with Spinner
 component in alert dialogs

---
 .../layout/providers/LayoutDataProvider.tsx       | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

diff --git a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
index fd6b45c52..6138b67fb 100644
--- a/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
+++ b/surfsense_web/components/layout/providers/LayoutDataProvider.tsx
@@ -775,7 +775,8 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 					<AlertDialogHeader>
 						<AlertDialogTitle>{t("delete_chat")}</AlertDialogTitle>
 						<AlertDialogDescription>
-							{t("delete_chat_confirm")} <span className="font-medium">{chatToDelete?.name}</span>?{" "}
+							{t("delete_chat_confirm")}{" "}
+							<span className="font-medium break-all">{chatToDelete?.name}</span>?{" "}
 							{t("action_cannot_undone")}
 						</AlertDialogDescription>
 					</AlertDialogHeader>
@@ -835,9 +836,7 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 							<span className={isRenamingChat ? "opacity-0" : ""}>
 								{tSidebar("rename") || "Rename"}
 							</span>
-							{isRenamingChat && (
-								<span className="absolute h-4 w-4 animate-spin rounded-full border-2 border-current border-t-transparent" />
-							)}
+							{isRenamingChat && <Spinner size="sm" className="absolute" />}
 						</Button>
 					</DialogFooter>
 				</DialogContent>
@@ -865,9 +864,7 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 							className="relative bg-destructive text-destructive-foreground hover:bg-destructive/90"
 						>
 							<span className={isDeletingSearchSpace ? "opacity-0" : ""}>{tCommon("delete")}</span>
-							{isDeletingSearchSpace && (
-								<span className="absolute h-4 w-4 animate-spin rounded-full border-2 border-current border-t-transparent" />
-							)}
+							{isDeletingSearchSpace && <Spinner size="sm" className="absolute" />}
 						</AlertDialogAction>
 					</AlertDialogFooter>
 				</AlertDialogContent>
@@ -895,9 +892,7 @@ export function LayoutDataProvider({ searchSpaceId, children }: LayoutDataProvid
 							className="relative bg-destructive text-destructive-foreground hover:bg-destructive/90"
 						>
 							<span className={isLeavingSearchSpace ? "opacity-0" : ""}>{t("leave")}</span>
-							{isLeavingSearchSpace && (
-								<span className="absolute h-4 w-4 animate-spin rounded-full border-2 border-current border-t-transparent" />
-							)}
+							{isLeavingSearchSpace && <Spinner size="sm" className="absolute" />}
 						</AlertDialogAction>
 					</AlertDialogFooter>
 				</AlertDialogContent>

From d2cf3fb3b7eafce01c881e80049346239c84bc6f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 09:58:14 +0530
Subject: [PATCH 09/70] refactor: update LLM role management logic and enhance
 UI feedback

---
 .../new-llm-config-mutation.atoms.ts          |   9 +-
 .../components/settings/llm-role-manager.tsx  | 165 +++++-------------
 2 files changed, 52 insertions(+), 122 deletions(-)

diff --git a/surfsense_web/atoms/new-llm-config/new-llm-config-mutation.atoms.ts b/surfsense_web/atoms/new-llm-config/new-llm-config-mutation.atoms.ts
index 861606f80..d6d3aa820 100644
--- a/surfsense_web/atoms/new-llm-config/new-llm-config-mutation.atoms.ts
+++ b/surfsense_web/atoms/new-llm-config/new-llm-config-mutation.atoms.ts
@@ -109,10 +109,11 @@ export const updateLLMPreferencesMutationAtom = atomWithMutation((get) => {
 		mutationFn: async (request: UpdateLLMPreferencesRequest) => {
 			return newLLMConfigApiService.updateLLMPreferences(request);
 		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({
-				queryKey: cacheKeys.newLLMConfigs.preferences(Number(searchSpaceId)),
-			});
+		onSuccess: (_data, request: UpdateLLMPreferencesRequest) => {
+			queryClient.setQueryData(
+				cacheKeys.newLLMConfigs.preferences(Number(searchSpaceId)),
+				(old: Record<string, unknown> | undefined) => ({ ...old, ...request.data })
+			);
 		},
 		onError: (error: Error) => {
 			toast.error(error.message || "Failed to update LLM preferences");
diff --git a/surfsense_web/components/settings/llm-role-manager.tsx b/surfsense_web/components/settings/llm-role-manager.tsx
index 07ec492a3..22e17e431 100644
--- a/surfsense_web/components/settings/llm-role-manager.tsx
+++ b/surfsense_web/components/settings/llm-role-manager.tsx
@@ -4,16 +4,14 @@ import { useAtomValue } from "jotai";
 import {
 	AlertCircle,
 	Bot,
-	CheckCircle,
+	CircleCheck,
 	CircleDashed,
 	FileText,
 	ImageIcon,
 	RefreshCw,
-	RotateCcw,
-	Save,
 	Shuffle,
 } from "lucide-react";
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import { toast } from "sonner";
 import {
 	globalImageGenConfigsAtom,
@@ -40,6 +38,7 @@ import {
 	SelectValue,
 } from "@/components/ui/select";
 import { Skeleton } from "@/components/ui/skeleton";
+import { Spinner } from "@/components/ui/spinner";
 import { getProviderIcon } from "@/lib/provider-icons";
 import { cn } from "@/lib/utils";
 
@@ -48,8 +47,8 @@ const ROLE_DESCRIPTIONS = {
 		icon: Bot,
 		title: "Agent LLM",
 		description: "Primary LLM for chat interactions and agent operations",
-		color: "text-blue-600 dark:text-blue-400",
-		bgColor: "bg-blue-500/10",
+		color: "text-muted-foreground",
+		bgColor: "bg-muted",
 		prefKey: "agent_llm_id" as const,
 		configType: "llm" as const,
 	},
@@ -57,8 +56,8 @@ const ROLE_DESCRIPTIONS = {
 		icon: FileText,
 		title: "Document Summary LLM",
 		description: "Handles document summarization and research synthesis",
-		color: "text-purple-600 dark:text-purple-400",
-		bgColor: "bg-purple-500/10",
+		color: "text-muted-foreground",
+		bgColor: "bg-muted",
 		prefKey: "document_summary_llm_id" as const,
 		configType: "llm" as const,
 	},
@@ -66,8 +65,8 @@ const ROLE_DESCRIPTIONS = {
 		icon: ImageIcon,
 		title: "Image Generation Model",
 		description: "Model used for AI image generation (DALL-E, GPT Image, etc.)",
-		color: "text-teal-600 dark:text-teal-400",
-		bgColor: "bg-teal-500/10",
+		color: "text-muted-foreground",
+		bgColor: "bg-muted",
 		prefKey: "image_generation_config_id" as const,
 		configType: "image" as const,
 	},
@@ -118,88 +117,41 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 		image_generation_config_id: preferences.image_generation_config_id ?? "",
 	}));
 
-	const [hasChanges, setHasChanges] = useState(false);
-	const [isSaving, setIsSaving] = useState(false);
+	const [savingRole, setSavingRole] = useState<string | null>(null);
+	const savingRef = useRef(false);
 
 	useEffect(() => {
-		const newAssignments = {
-			agent_llm_id: preferences.agent_llm_id ?? "",
-			document_summary_llm_id: preferences.document_summary_llm_id ?? "",
-			image_generation_config_id: preferences.image_generation_config_id ?? "",
-		};
-		setAssignments(newAssignments);
-		setHasChanges(false);
+		if (!savingRef.current) {
+			setAssignments({
+				agent_llm_id: preferences.agent_llm_id ?? "",
+				document_summary_llm_id: preferences.document_summary_llm_id ?? "",
+				image_generation_config_id: preferences.image_generation_config_id ?? "",
+			});
+		}
 	}, [
 		preferences?.agent_llm_id,
 		preferences?.document_summary_llm_id,
 		preferences?.image_generation_config_id,
 	]);
 
-	const handleRoleAssignment = (prefKey: string, configId: string) => {
-		const newAssignments = {
-			...assignments,
-			[prefKey]: configId === "unassigned" ? "" : parseInt(configId),
-		};
+	const handleRoleAssignment = useCallback(async (prefKey: string, configId: string) => {
+		const value = configId === "unassigned" ? "" : parseInt(configId);
 
-		setAssignments(newAssignments);
+		setAssignments((prev) => ({ ...prev, [prefKey]: value }));
+		setSavingRole(prefKey);
+		savingRef.current = true;
 
-		const currentPrefs = {
-			agent_llm_id: preferences.agent_llm_id ?? "",
-			document_summary_llm_id: preferences.document_summary_llm_id ?? "",
-			image_generation_config_id: preferences.image_generation_config_id ?? "",
-		};
-
-		const hasChangesNow = Object.keys(newAssignments).some(
-			(key) =>
-				newAssignments[key as keyof typeof newAssignments] !==
-				currentPrefs[key as keyof typeof currentPrefs]
-		);
-
-		setHasChanges(hasChangesNow);
-	};
-
-	const handleSave = async () => {
-		setIsSaving(true);
-
-		const toNumericOrUndefined = (val: string | number) =>
-			typeof val === "string" ? (val ? parseInt(val) : undefined) : val;
-
-		const numericAssignments = {
-			agent_llm_id: toNumericOrUndefined(assignments.agent_llm_id),
-			document_summary_llm_id: toNumericOrUndefined(assignments.document_summary_llm_id),
-			image_generation_config_id: toNumericOrUndefined(assignments.image_generation_config_id),
-		};
-
-		await updatePreferences({
-			search_space_id: searchSpaceId,
-			data: numericAssignments,
-		});
-
-		setHasChanges(false);
-		toast.success("Role assignments saved successfully!");
-
-		setIsSaving(false);
-	};
-
-	const handleReset = () => {
-		setAssignments({
-			agent_llm_id: preferences.agent_llm_id ?? "",
-			document_summary_llm_id: preferences.document_summary_llm_id ?? "",
-			image_generation_config_id: preferences.image_generation_config_id ?? "",
-		});
-		setHasChanges(false);
-	};
-
-	const isAssignmentComplete =
-		assignments.agent_llm_id !== "" &&
-		assignments.agent_llm_id !== null &&
-		assignments.agent_llm_id !== undefined &&
-		assignments.document_summary_llm_id !== "" &&
-		assignments.document_summary_llm_id !== null &&
-		assignments.document_summary_llm_id !== undefined &&
-		assignments.image_generation_config_id !== "" &&
-		assignments.image_generation_config_id !== null &&
-		assignments.image_generation_config_id !== undefined;
+		try {
+			await updatePreferences({
+				search_space_id: searchSpaceId,
+				data: { [prefKey]: value || undefined },
+			});
+			toast.success("Role assignment updated");
+		} finally {
+			setSavingRole(null);
+			savingRef.current = false;
+		}
+	}, [updatePreferences, searchSpaceId]);
 
 	// Combine global and custom LLM configs
 	const allLLMConfigs = [
@@ -213,6 +165,11 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 		...(userImageConfigs ?? []).filter((config) => config.id && config.id.toString().trim() !== ""),
 	];
 
+	const isAssignmentComplete =
+		allLLMConfigs.some((c) => c.id === assignments.agent_llm_id) &&
+		allLLMConfigs.some((c) => c.id === assignments.document_summary_llm_id) &&
+		allImageConfigs.some((c) => c.id === assignments.image_generation_config_id);
+
 	const isLoading =
 		configsLoading ||
 		preferencesLoading ||
@@ -244,9 +201,9 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 				{isAssignmentComplete && !isLoading && !hasError && (
 					<Badge
 						variant="outline"
-						className="text-xs gap-1.5 border-emerald-500/30 text-emerald-700 dark:text-emerald-300 bg-emerald-500/5"
+						className="text-xs gap-1.5 text-muted-foreground"
 					>
-						<CheckCircle className="h-3 w-3" />
+						<CircleCheck className="h-3 w-3" />
 						All roles assigned
 					</Badge>
 				)}
@@ -332,10 +289,7 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 						const roleAllConfigs = isImageRole ? allImageConfigs : allLLMConfigs;
 
 						const assignedConfig = roleAllConfigs.find((config) => config.id === currentAssignment);
-						const isAssigned =
-							currentAssignment !== "" &&
-							currentAssignment !== null &&
-							currentAssignment !== undefined;
+						const isAssigned = !!assignedConfig;
 						const isAutoMode =
 							assignedConfig && "is_auto_mode" in assignedConfig && assignedConfig.is_auto_mode;
 
@@ -361,8 +315,10 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 													</p>
 												</div>
 											</div>
-											{isAssigned ? (
-												<CheckCircle className="w-4 h-4 text-emerald-500 shrink-0 mt-0.5" />
+											{savingRole === role.prefKey ? (
+												<Spinner size="sm" className="shrink-0 mt-0.5 text-muted-foreground" />
+											) : isAssigned ? (
+												<CircleCheck className="w-4 h-4 text-muted-foreground/40 shrink-0 mt-0.5" />
 											) : (
 												<CircleDashed className="w-4 h-4 text-muted-foreground/40 shrink-0 mt-0.5" />
 											)}
@@ -374,7 +330,7 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 												Configuration
 											</Label>
 											<Select
-												value={currentAssignment?.toString() || "unassigned"}
+												value={isAssigned ? currentAssignment.toString() : "unassigned"}
 												onValueChange={(value) => handleRoleAssignment(role.prefKey, value)}
 											>
 												<SelectTrigger className="w-full h-9 md:h-10 text-xs md:text-sm">
@@ -534,33 +490,6 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 				</div>
 			)}
 
-			{/* Save / Reset Bar */}
-			{hasChanges && (
-				<div className="flex items-center justify-between gap-3 rounded-lg border border-border bg-muted/50 p-3 md:p-4">
-					<p className="text-xs md:text-sm text-muted-foreground">You have unsaved changes</p>
-					<div className="flex items-center gap-2">
-						<Button
-							variant="outline"
-							size="sm"
-							onClick={handleReset}
-							disabled={isSaving}
-							className="h-8 text-xs gap-1.5"
-						>
-							<RotateCcw className="w-3 h-3" />
-							Reset
-						</Button>
-						<Button
-							size="sm"
-							onClick={handleSave}
-							disabled={isSaving}
-							className="h-8 text-xs gap-1.5"
-						>
-							<Save className="w-3 h-3" />
-							{isSaving ? "Saving…" : "Save Changes"}
-						</Button>
-					</div>
-				</div>
-			)}
 		</div>
 	);
 }

From 000c2d9b5b670804c0c3cf09294a5af12322e7d6 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 10:11:35 +0530
Subject: [PATCH 10/70] style: simplify LLM model terminology in UI

---
 docs/chinese-llm-setup.md                              |  2 +-
 .../alembic/versions/51_add_new_llm_config_table.py    |  6 +++---
 .../app/config/global_llm_config.example.yaml          |  2 +-
 surfsense_backend/app/indexing_pipeline/exceptions.py  |  4 ++--
 surfsense_backend/app/routes/__init__.py               |  2 +-
 surfsense_backend/app/routes/model_list_routes.py      |  4 ++--
 surfsense_backend/app/routes/new_llm_config_routes.py  |  2 +-
 surfsense_backend/app/schemas/new_llm_config.py        | 10 +++++-----
 surfsense_backend/app/services/model_list_service.py   |  2 +-
 .../new-llm-config/new-llm-config-mutation.atoms.ts    |  2 +-
 .../atoms/new-llm-config/new-llm-config-query.atoms.ts |  2 +-
 surfsense_web/components/new-chat/model-selector.tsx   |  2 +-
 .../components/settings/model-config-manager.tsx       | 10 +++++-----
 surfsense_web/content/docs/testing.mdx                 |  2 +-
 surfsense_web/contracts/enums/llm-models.ts            |  2 +-
 surfsense_web/contracts/types/new-llm-config.types.ts  |  6 +++---
 surfsense_web/lib/apis/new-llm-config-api.service.ts   |  2 +-
 surfsense_web/messages/en.json                         |  2 +-
 18 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/docs/chinese-llm-setup.md b/docs/chinese-llm-setup.md
index 1fb0ce2a1..6638dbba1 100644
--- a/docs/chinese-llm-setup.md
+++ b/docs/chinese-llm-setup.md
@@ -24,7 +24,7 @@ SurfSense 现已支持以下国产 LLM：
 
 1. 登录 SurfSense Dashboard
 2. 进入 **Settings** → **API Keys** (或 **LLM Configurations**)
-3. 点击 **Add LLM Model**
+3. 点击 **Add Model**
 4. 从 **Provider** 下拉菜单中选择你的国产 LLM 提供商
 5. 填写必填字段（见下方各提供商详细配置）
 6. 点击 **Save**
diff --git a/surfsense_backend/alembic/versions/51_add_new_llm_config_table.py b/surfsense_backend/alembic/versions/51_add_new_llm_config_table.py
index 89a5c1246..7d90f4b13 100644
--- a/surfsense_backend/alembic/versions/51_add_new_llm_config_table.py
+++ b/surfsense_backend/alembic/versions/51_add_new_llm_config_table.py
@@ -17,10 +17,10 @@ depends_on: str | Sequence[str] | None = None
 
 def upgrade() -> None:
     """
-    Add the new_llm_configs table that combines LLM model settings with prompt configuration.
+    Add the new_llm_configs table that combines model settings with prompt configuration.
 
     This table includes:
-    - LLM model configuration (provider, model_name, api_key, etc.)
+    - Model configuration (provider, model_name, api_key, etc.)
     - Configurable system instructions
     - Citation toggle
     """
@@ -41,7 +41,7 @@ def upgrade() -> None:
                     name VARCHAR(100) NOT NULL,
                     description VARCHAR(500),
                     
-                    -- LLM Model Configuration (same as llm_configs, excluding language)
+                    -- Model Configuration (same as llm_configs, excluding language)
                     provider litellmprovider NOT NULL,
                     custom_provider VARCHAR(100),
                     model_name VARCHAR(100) NOT NULL,
diff --git a/surfsense_backend/app/config/global_llm_config.example.yaml b/surfsense_backend/app/config/global_llm_config.example.yaml
index 6ca3e95e3..49a8d0295 100644
--- a/surfsense_backend/app/config/global_llm_config.example.yaml
+++ b/surfsense_backend/app/config/global_llm_config.example.yaml
@@ -17,7 +17,7 @@
 # - Configure router_settings below to customize the load balancing behavior
 #
 # Structure matches NewLLMConfig:
-# - LLM model configuration (provider, model_name, api_key, etc.)
+# - Model configuration (provider, model_name, api_key, etc.)
 # - Prompt configuration (system_instructions, citations_enabled)
 
 # Router Settings for Auto Mode
diff --git a/surfsense_backend/app/indexing_pipeline/exceptions.py b/surfsense_backend/app/indexing_pipeline/exceptions.py
index 9155e9baa..666fa4b9f 100644
--- a/surfsense_backend/app/indexing_pipeline/exceptions.py
+++ b/surfsense_backend/app/indexing_pipeline/exceptions.py
@@ -59,7 +59,7 @@ class PipelineMessages:
 
     LLM_AUTH = "LLM authentication failed. Check your API key."
     LLM_PERMISSION = "LLM request denied. Check your account permissions."
-    LLM_NOT_FOUND = "LLM model not found. Check your model configuration."
+    LLM_NOT_FOUND = "Model not found. Check your model configuration."
     LLM_BAD_REQUEST = "LLM rejected the request. Document content may be invalid."
     LLM_UNPROCESSABLE = (
         "Document exceeds the LLM context window even after optimization."
@@ -67,7 +67,7 @@ class PipelineMessages:
     LLM_RESPONSE = "LLM returned an invalid response."
     LLM_AUTH = "LLM authentication failed. Check your API key."
     LLM_PERMISSION = "LLM request denied. Check your account permissions."
-    LLM_NOT_FOUND = "LLM model not found. Check your model configuration."
+    LLM_NOT_FOUND = "Model not found. Check your model configuration."
     LLM_BAD_REQUEST = "LLM rejected the request. Document content may be invalid."
     LLM_UNPROCESSABLE = (
         "Document exceeds the LLM context window even after optimization."
diff --git a/surfsense_backend/app/routes/__init__.py b/surfsense_backend/app/routes/__init__.py
index 1937f11cb..efa0ff2f6 100644
--- a/surfsense_backend/app/routes/__init__.py
+++ b/surfsense_backend/app/routes/__init__.py
@@ -84,7 +84,7 @@ router.include_router(confluence_add_connector_router)
 router.include_router(clickup_add_connector_router)
 router.include_router(dropbox_add_connector_router)
 router.include_router(new_llm_config_router)  # LLM configs with prompt configuration
-router.include_router(model_list_router)  # Dynamic LLM model catalogue from OpenRouter
+router.include_router(model_list_router)  # Dynamic model catalogue from OpenRouter
 router.include_router(logs_router)
 router.include_router(circleback_webhook_router)  # Circleback meeting webhooks
 router.include_router(surfsense_docs_router)  # Surfsense documentation for citations
diff --git a/surfsense_backend/app/routes/model_list_routes.py b/surfsense_backend/app/routes/model_list_routes.py
index ef6e30514..79ae7221f 100644
--- a/surfsense_backend/app/routes/model_list_routes.py
+++ b/surfsense_backend/app/routes/model_list_routes.py
@@ -1,5 +1,5 @@
 """
-API route for fetching the available LLM models catalogue.
+API route for fetching the available models catalogue.
 
 Serves a dynamically-updated list sourced from the OpenRouter public API,
 with a local JSON fallback when the API is unreachable.
@@ -30,7 +30,7 @@ async def list_available_models(
     user: User = Depends(current_active_user),
 ):
     """
-    Return all available LLM models grouped by provider.
+    Return all available models grouped by provider.
 
     The list is sourced from the OpenRouter public API and cached for 1 hour.
     If the API is unreachable, a local fallback file is used instead.
diff --git a/surfsense_backend/app/routes/new_llm_config_routes.py b/surfsense_backend/app/routes/new_llm_config_routes.py
index f784bd273..78907c719 100644
--- a/surfsense_backend/app/routes/new_llm_config_routes.py
+++ b/surfsense_backend/app/routes/new_llm_config_routes.py
@@ -1,7 +1,7 @@
 """
 API routes for NewLLMConfig CRUD operations.
 
-NewLLMConfig combines LLM model settings with prompt configuration:
+NewLLMConfig combines model settings with prompt configuration:
 - LLM provider, model, API key, etc.
 - Configurable system instructions
 - Citation toggle
diff --git a/surfsense_backend/app/schemas/new_llm_config.py b/surfsense_backend/app/schemas/new_llm_config.py
index 9863665b6..15ed4ce67 100644
--- a/surfsense_backend/app/schemas/new_llm_config.py
+++ b/surfsense_backend/app/schemas/new_llm_config.py
@@ -1,7 +1,7 @@
 """
 Pydantic schemas for the NewLLMConfig API.
 
-NewLLMConfig combines LLM model settings with prompt configuration:
+NewLLMConfig combines model settings with prompt configuration:
 - LLM provider, model, API key, etc.
 - Configurable system instructions
 - Citation toggle
@@ -26,7 +26,7 @@ class NewLLMConfigBase(BaseModel):
         None, max_length=500, description="Optional description"
     )
 
-    # LLM Model Configuration
+    # Model Configuration
     provider: LiteLLMProvider = Field(..., description="LiteLLM provider type")
     custom_provider: str | None = Field(
         None, max_length=100, description="Custom provider name when provider is CUSTOM"
@@ -71,7 +71,7 @@ class NewLLMConfigUpdate(BaseModel):
     name: str | None = Field(None, max_length=100)
     description: str | None = Field(None, max_length=500)
 
-    # LLM Model Configuration
+    # Model Configuration
     provider: LiteLLMProvider | None = None
     custom_provider: str | None = Field(None, max_length=100)
     model_name: str | None = Field(None, max_length=100)
@@ -106,7 +106,7 @@ class NewLLMConfigPublic(BaseModel):
     name: str
     description: str | None = None
 
-    # LLM Model Configuration (no api_key)
+    # Model Configuration (no api_key)
     provider: LiteLLMProvider
     custom_provider: str | None = None
     model_name: str
@@ -149,7 +149,7 @@ class GlobalNewLLMConfigRead(BaseModel):
     name: str
     description: str | None = None
 
-    # LLM Model Configuration (no api_key)
+    # Model Configuration (no api_key)
     provider: str  # String because YAML doesn't enforce enum, "AUTO" for Auto mode
     custom_provider: str | None = None
     model_name: str
diff --git a/surfsense_backend/app/services/model_list_service.py b/surfsense_backend/app/services/model_list_service.py
index ebc0e0d7c..2a81c2d52 100644
--- a/surfsense_backend/app/services/model_list_service.py
+++ b/surfsense_backend/app/services/model_list_service.py
@@ -1,5 +1,5 @@
 """
-Service for fetching and caching the available LLM model list.
+Service for fetching and caching the available model list.
 
 Uses the OpenRouter public API as the primary source, with a local
 fallback JSON file when the API is unreachable.
diff --git a/surfsense_web/atoms/new-llm-config/new-llm-config-mutation.atoms.ts b/surfsense_web/atoms/new-llm-config/new-llm-config-mutation.atoms.ts
index d6d3aa820..2a048ca3e 100644
--- a/surfsense_web/atoms/new-llm-config/new-llm-config-mutation.atoms.ts
+++ b/surfsense_web/atoms/new-llm-config/new-llm-config-mutation.atoms.ts
@@ -34,7 +34,7 @@ export const createNewLLMConfigMutationAtom = atomWithMutation((get) => {
 			});
 		},
 		onError: (error: Error) => {
-			toast.error(error.message || "Failed to create LLM model");
+			toast.error(error.message || "Failed to create model");
 		},
 	};
 });
diff --git a/surfsense_web/atoms/new-llm-config/new-llm-config-query.atoms.ts b/surfsense_web/atoms/new-llm-config/new-llm-config-query.atoms.ts
index e4c8bcffc..32250d394 100644
--- a/surfsense_web/atoms/new-llm-config/new-llm-config-query.atoms.ts
+++ b/surfsense_web/atoms/new-llm-config/new-llm-config-query.atoms.ts
@@ -66,7 +66,7 @@ export const defaultSystemInstructionsAtom = atomWithQuery(() => {
 });
 
 /**
- * Query atom for the dynamic LLM model catalogue.
+ * Query atom for the dynamic model catalogue.
  * Fetched from the backend (which proxies OpenRouter's public API).
  * Falls back to the static hardcoded list on error.
  */
diff --git a/surfsense_web/components/new-chat/model-selector.tsx b/surfsense_web/components/new-chat/model-selector.tsx
index 7a2a471ba..b207d82b4 100644
--- a/surfsense_web/components/new-chat/model-selector.tsx
+++ b/surfsense_web/components/new-chat/model-selector.tsx
@@ -498,7 +498,7 @@ export function ModelSelector({
 										}}
 									>
 										<Plus className="size-4 text-primary" />
-										<span className="text-sm font-medium">Add LLM Model</span>
+										<span className="text-sm font-medium">Add Model</span>
 									</Button>
 								</div>
 							</CommandList>
diff --git a/surfsense_web/components/settings/model-config-manager.tsx b/surfsense_web/components/settings/model-config-manager.tsx
index 837060c70..79504451a 100644
--- a/surfsense_web/components/settings/model-config-manager.tsx
+++ b/surfsense_web/components/settings/model-config-manager.tsx
@@ -150,7 +150,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 						onClick={openNewDialog}
 						className="gap-2 bg-white text-black hover:bg-neutral-100 dark:bg-white dark:text-black dark:hover:bg-neutral-200"
 					>
-						Add LLM Model
+						Add Model
 					</Button>
 				)}
 			</div>
@@ -252,11 +252,11 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 						<div>
 							<Card className="border-0 bg-transparent shadow-none">
 								<CardContent className="flex flex-col items-center justify-center py-10 md:py-16 text-center">
-									<h3 className="text-sm md:text-base font-semibold mb-2">No LLM Models Yet</h3>
+									<h3 className="text-sm md:text-base font-semibold mb-2">No Models Yet</h3>
 									<p className="text-[11px] md:text-xs text-muted-foreground max-w-sm mb-4">
 										{canCreate
-											? "Add your first LLM model to power document summarization, chat, and other agent capabilities"
-											: "No LLM models have been added to this space yet. Contact a space owner to add one"}
+											? "Add your first model to power document summarization, chat, and other agent capabilities"
+											: "No models have been added to this space yet. Contact a space owner to add one"}
 									</p>
 								</CardContent>
 							</Card>
@@ -420,7 +420,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 			>
 				<AlertDialogContent className="select-none">
 					<AlertDialogHeader>
-						<AlertDialogTitle>Delete LLM Model</AlertDialogTitle>
+						<AlertDialogTitle>Delete Model</AlertDialogTitle>
 						<AlertDialogDescription>
 							Are you sure you want to delete{" "}
 							<span className="font-semibold text-foreground">{configToDelete?.name}</span>? This
diff --git a/surfsense_web/content/docs/testing.mdx b/surfsense_web/content/docs/testing.mdx
index 9c4682b90..c6739de10 100644
--- a/surfsense_web/content/docs/testing.mdx
+++ b/surfsense_web/content/docs/testing.mdx
@@ -10,7 +10,7 @@ SurfSense uses [pytest](https://docs.pytest.org/) with two test layers: **unit**
 
 - **PostgreSQL + pgvector** running locally (database `surfsense_test` will be used)
 - **`REGISTRATION_ENABLED=TRUE`** in your `.env` (this is the default)
-- A working LLM model with a valid API key in `global_llm_config.yaml` (for integration tests)
+- A working model with a valid API key in `global_llm_config.yaml` (for integration tests)
 
 No Redis or Celery is required — integration tests use an inline task dispatcher.
 
diff --git a/surfsense_web/contracts/enums/llm-models.ts b/surfsense_web/contracts/enums/llm-models.ts
index 31097ca6e..74cc056f3 100644
--- a/surfsense_web/contracts/enums/llm-models.ts
+++ b/surfsense_web/contracts/enums/llm-models.ts
@@ -5,7 +5,7 @@ export interface LLMModel {
 	contextWindow?: string;
 }
 
-// Comprehensive LLM models database organized by provider
+// Comprehensive models database organized by provider
 export const LLM_MODELS: LLMModel[] = [
 	// OpenAI
 	{
diff --git a/surfsense_web/contracts/types/new-llm-config.types.ts b/surfsense_web/contracts/types/new-llm-config.types.ts
index 3bb43680a..4422857ab 100644
--- a/surfsense_web/contracts/types/new-llm-config.types.ts
+++ b/surfsense_web/contracts/types/new-llm-config.types.ts
@@ -41,14 +41,14 @@ export const liteLLMProviderEnum = z.enum([
 export type LiteLLMProvider = z.infer<typeof liteLLMProviderEnum>;
 
 /**
- * NewLLMConfig - combines LLM model settings with prompt configuration
+ * NewLLMConfig - combines model settings with prompt configuration
  */
 export const newLLMConfig = z.object({
 	id: z.number(),
 	name: z.string().max(100),
 	description: z.string().max(500).nullable().optional(),
 
-	// LLM Model Configuration
+	// Model Configuration
 	provider: liteLLMProviderEnum,
 	custom_provider: z.string().max(100).nullable().optional(),
 	model_name: z.string().max(100),
@@ -148,7 +148,7 @@ export const globalNewLLMConfig = z.object({
 	name: z.string(),
 	description: z.string().nullable().optional(),
 
-	// LLM Model Configuration (no api_key)
+	// Model Configuration (no api_key)
 	provider: z.string(), // String because YAML doesn't enforce enum, "AUTO" for Auto mode
 	custom_provider: z.string().nullable().optional(),
 	model_name: z.string(),
diff --git a/surfsense_web/lib/apis/new-llm-config-api.service.ts b/surfsense_web/lib/apis/new-llm-config-api.service.ts
index 71af1a8d9..a1040a9bc 100644
--- a/surfsense_web/lib/apis/new-llm-config-api.service.ts
+++ b/surfsense_web/lib/apis/new-llm-config-api.service.ts
@@ -147,7 +147,7 @@ class NewLLMConfigApiService {
 	};
 
 	/**
-	 * Get the dynamic LLM model catalogue (sourced from OpenRouter API)
+	 * Get the dynamic model catalogue (sourced from OpenRouter API)
 	 */
 	getModels = async () => {
 		return baseApiService.get(`/api/v1/models`, getModelListResponse);
diff --git a/surfsense_web/messages/en.json b/surfsense_web/messages/en.json
index 53f80ea5f..4310bc707 100644
--- a/surfsense_web/messages/en.json
+++ b/surfsense_web/messages/en.json
@@ -737,7 +737,7 @@
 		"nav_general": "General",
 		"nav_general_desc": "Name, description & basic info",
 		"nav_agent_configs": "Agent Configs",
-		"nav_agent_configs_desc": "LLM models with prompts & citations",
+		"nav_agent_configs_desc": "Models with prompts & citations",
 		"nav_role_assignments": "Role Assignments",
 		"nav_role_assignments_desc": "Assign configs to agent roles",
 		"nav_image_models": "Image Models",

From c9ae4fcaca3ce8178c26485ef6290010e0327c62 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 10:12:34 +0530
Subject: [PATCH 11/70] style: update badge component in LLM role manager for
 improved visual consistency

---
 surfsense_web/components/settings/llm-role-manager.tsx | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/surfsense_web/components/settings/llm-role-manager.tsx b/surfsense_web/components/settings/llm-role-manager.tsx
index 22e17e431..d1651b7f0 100644
--- a/surfsense_web/components/settings/llm-role-manager.tsx
+++ b/surfsense_web/components/settings/llm-role-manager.tsx
@@ -360,13 +360,7 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 																	>
 																		<div className="flex items-center gap-1 md:gap-1.5 flex-wrap min-w-0">
 																			{isAuto ? (
-																				<Badge
-																					variant="outline"
-																					className="text-[9px] md:text-[10px] shrink-0 bg-violet-100 text-violet-700 dark:bg-violet-900/30 dark:text-violet-300 border-violet-200 dark:border-violet-700"
-																				>
-																					<Shuffle className="size-2 md:size-2.5 mr-0.5" />
-																					AUTO
-																				</Badge>
+																				<Shuffle className="size-3 md:size-3.5 shrink-0 text-muted-foreground" />
 																			) : (
 																				getProviderIcon(config.provider, {
 																					className: "size-3 md:size-3.5 shrink-0",

From 3b92e99d28087554bd23b6b9b95ccb8b32433a0c Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 10:35:32 +0530
Subject: [PATCH 12/70] feat: add local folder connector and document
 versioning functionality

---
 ...d_local_folder_connector_and_versioning.py | 135 ++++++++++++
 surfsense_backend/app/db.py                   |  22 ++
 .../app/routes/documents_routes.py            | 123 +++++++++++
 .../routes/search_source_connectors_routes.py | 195 ++++++++++++++++--
 4 files changed, 459 insertions(+), 16 deletions(-)
 create mode 100644 surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py

diff --git a/surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py b/surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py
new file mode 100644
index 000000000..e97a4787c
--- /dev/null
+++ b/surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py
@@ -0,0 +1,135 @@
+"""Add local folder connector enums and document_versions table
+
+Revision ID: 117
+Revises: 116
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "117"
+down_revision: str | None = "116"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+PUBLICATION_NAME = "zero_publication"
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+
+    # Add LOCAL_FOLDER_CONNECTOR to searchsourceconnectortype enum
+    op.execute(
+        """
+    DO $$
+    BEGIN
+        IF NOT EXISTS (
+            SELECT 1 FROM pg_type t
+            JOIN pg_enum e ON t.oid = e.enumtypid
+            WHERE t.typname = 'searchsourceconnectortype' AND e.enumlabel = 'LOCAL_FOLDER_CONNECTOR'
+        ) THEN
+            ALTER TYPE searchsourceconnectortype ADD VALUE 'LOCAL_FOLDER_CONNECTOR';
+        END IF;
+    END
+    $$;
+    """
+    )
+
+    # Add LOCAL_FOLDER_FILE to documenttype enum
+    op.execute(
+        """
+    DO $$
+    BEGIN
+        IF NOT EXISTS (
+            SELECT 1 FROM pg_type t
+            JOIN pg_enum e ON t.oid = e.enumtypid
+            WHERE t.typname = 'documenttype' AND e.enumlabel = 'LOCAL_FOLDER_FILE'
+        ) THEN
+            ALTER TYPE documenttype ADD VALUE 'LOCAL_FOLDER_FILE';
+        END IF;
+    END
+    $$;
+    """
+    )
+
+    # Create document_versions table
+    table_exists = conn.execute(
+        sa.text(
+            "SELECT 1 FROM information_schema.tables WHERE table_name = 'document_versions'"
+        )
+    ).fetchone()
+    if not table_exists:
+        op.create_table(
+            "document_versions",
+            sa.Column("id", sa.Integer(), nullable=False, autoincrement=True),
+            sa.Column("document_id", sa.Integer(), nullable=False),
+            sa.Column("version_number", sa.Integer(), nullable=False),
+            sa.Column("source_markdown", sa.Text(), nullable=True),
+            sa.Column("content_hash", sa.String(), nullable=False),
+            sa.Column("title", sa.String(), nullable=True),
+            sa.Column(
+                "created_at",
+                sa.TIMESTAMP(timezone=True),
+                server_default=sa.text("now()"),
+                nullable=False,
+            ),
+            sa.ForeignKeyConstraint(
+                ["document_id"],
+                ["documents.id"],
+                ondelete="CASCADE",
+            ),
+            sa.PrimaryKeyConstraint("id"),
+            sa.UniqueConstraint(
+                "document_id",
+                "version_number",
+                name="uq_document_version",
+            ),
+        )
+
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_document_versions_document_id "
+        "ON document_versions (document_id)"
+    )
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_document_versions_created_at "
+        "ON document_versions (created_at)"
+    )
+
+    # Add document_versions to Zero publication
+    pub_exists = conn.execute(
+        sa.text("SELECT 1 FROM pg_publication WHERE pubname = :name"),
+        {"name": PUBLICATION_NAME},
+    ).fetchone()
+    if pub_exists:
+        already_in_pub = conn.execute(
+            sa.text(
+                "SELECT 1 FROM pg_publication_tables "
+                "WHERE pubname = :name AND tablename = 'document_versions'"
+            ),
+            {"name": PUBLICATION_NAME},
+        ).fetchone()
+        if not already_in_pub:
+            op.execute(
+                f"ALTER PUBLICATION {PUBLICATION_NAME} ADD TABLE document_versions"
+            )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+
+    # Remove from publication
+    pub_exists = conn.execute(
+        sa.text("SELECT 1 FROM pg_publication WHERE pubname = :name"),
+        {"name": PUBLICATION_NAME},
+    ).fetchone()
+    if pub_exists:
+        op.execute(
+            f"ALTER PUBLICATION {PUBLICATION_NAME} DROP TABLE IF EXISTS document_versions"
+        )
+
+    op.execute("DROP INDEX IF EXISTS ix_document_versions_created_at")
+    op.execute("DROP INDEX IF EXISTS ix_document_versions_document_id")
+    op.execute("DROP TABLE IF EXISTS document_versions")
diff --git a/surfsense_backend/app/db.py b/surfsense_backend/app/db.py
index 90630cc83..25045e84a 100644
--- a/surfsense_backend/app/db.py
+++ b/surfsense_backend/app/db.py
@@ -64,6 +64,7 @@ class DocumentType(StrEnum):
     COMPOSIO_GOOGLE_DRIVE_CONNECTOR = "COMPOSIO_GOOGLE_DRIVE_CONNECTOR"
     COMPOSIO_GMAIL_CONNECTOR = "COMPOSIO_GMAIL_CONNECTOR"
     COMPOSIO_GOOGLE_CALENDAR_CONNECTOR = "COMPOSIO_GOOGLE_CALENDAR_CONNECTOR"
+    LOCAL_FOLDER_FILE = "LOCAL_FOLDER_FILE"
 
 
 # Native Google document types → their legacy Composio equivalents.
@@ -109,6 +110,7 @@ class SearchSourceConnectorType(StrEnum):
     COMPOSIO_GOOGLE_DRIVE_CONNECTOR = "COMPOSIO_GOOGLE_DRIVE_CONNECTOR"
     COMPOSIO_GMAIL_CONNECTOR = "COMPOSIO_GMAIL_CONNECTOR"
     COMPOSIO_GOOGLE_CALENDAR_CONNECTOR = "COMPOSIO_GOOGLE_CALENDAR_CONNECTOR"
+    LOCAL_FOLDER_CONNECTOR = "LOCAL_FOLDER_CONNECTOR"
 
 
 class PodcastStatus(StrEnum):
@@ -1039,6 +1041,26 @@ class Document(BaseModel, TimestampMixin):
     )
 
 
+class DocumentVersion(BaseModel, TimestampMixin):
+    __tablename__ = "document_versions"
+    __table_args__ = (
+        UniqueConstraint("document_id", "version_number", name="uq_document_version"),
+    )
+
+    document_id = Column(
+        Integer,
+        ForeignKey("documents.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    version_number = Column(Integer, nullable=False)
+    source_markdown = Column(Text, nullable=True)
+    content_hash = Column(String, nullable=False)
+    title = Column(String, nullable=True)
+
+    document = relationship("Document", backref="versions")
+
+
 class Chunk(BaseModel, TimestampMixin):
     __tablename__ = "chunks"
 
diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index 6e69218f1..9271d4630 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -10,6 +10,7 @@ from app.db import (
     Chunk,
     Document,
     DocumentType,
+    DocumentVersion,
     Permission,
     SearchSpace,
     SearchSpaceMembership,
@@ -1135,3 +1136,125 @@ async def delete_document(
         raise HTTPException(
             status_code=500, detail=f"Failed to delete document: {e!s}"
         ) from e
+
+
+# ====================================================================
+# Version History Endpoints
+# ====================================================================
+
+
+@router.get("/documents/{document_id}/versions")
+async def list_document_versions(
+    document_id: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """List all versions for a document, ordered by version_number descending."""
+    document = (
+        await session.execute(select(Document).where(Document.id == document_id))
+    ).scalar_one_or_none()
+    if not document:
+        raise HTTPException(status_code=404, detail="Document not found")
+
+    await check_permission(session, user, document.search_space_id, Permission.READ)
+
+    versions = (
+        await session.execute(
+            select(DocumentVersion)
+            .where(DocumentVersion.document_id == document_id)
+            .order_by(DocumentVersion.version_number.desc())
+        )
+    ).scalars().all()
+
+    return [
+        {
+            "version_number": v.version_number,
+            "title": v.title,
+            "content_hash": v.content_hash,
+            "created_at": v.created_at.isoformat() if v.created_at else None,
+        }
+        for v in versions
+    ]
+
+
+@router.get("/documents/{document_id}/versions/{version_number}")
+async def get_document_version(
+    document_id: int,
+    version_number: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Get full version content including source_markdown."""
+    document = (
+        await session.execute(select(Document).where(Document.id == document_id))
+    ).scalar_one_or_none()
+    if not document:
+        raise HTTPException(status_code=404, detail="Document not found")
+
+    await check_permission(session, user, document.search_space_id, Permission.READ)
+
+    version = (
+        await session.execute(
+            select(DocumentVersion).where(
+                DocumentVersion.document_id == document_id,
+                DocumentVersion.version_number == version_number,
+            )
+        )
+    ).scalar_one_or_none()
+    if not version:
+        raise HTTPException(status_code=404, detail="Version not found")
+
+    return {
+        "version_number": version.version_number,
+        "title": version.title,
+        "content_hash": version.content_hash,
+        "source_markdown": version.source_markdown,
+        "created_at": version.created_at.isoformat() if version.created_at else None,
+    }
+
+
+@router.post("/documents/{document_id}/versions/{version_number}/restore")
+async def restore_document_version(
+    document_id: int,
+    version_number: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Restore a previous version: snapshot current state, then overwrite document content."""
+    document = (
+        await session.execute(
+            select(Document).where(Document.id == document_id)
+        )
+    ).scalar_one_or_none()
+    if not document:
+        raise HTTPException(status_code=404, detail="Document not found")
+
+    await check_permission(session, user, document.search_space_id, Permission.WRITE)
+
+    version = (
+        await session.execute(
+            select(DocumentVersion).where(
+                DocumentVersion.document_id == document_id,
+                DocumentVersion.version_number == version_number,
+            )
+        )
+    ).scalar_one_or_none()
+    if not version:
+        raise HTTPException(status_code=404, detail="Version not found")
+
+    # Snapshot current state before restoring
+    from app.utils.document_versioning import create_version_snapshot
+
+    await create_version_snapshot(session, document)
+
+    # Restore the version's content onto the document
+    document.source_markdown = version.source_markdown
+    document.title = version.title or document.title
+    document.content_needs_reindexing = True
+    await session.commit()
+
+    return {
+        "message": f"Restored version {version_number}",
+        "document_id": document_id,
+        "restored_version": version_number,
+    }
diff --git a/surfsense_backend/app/routes/search_source_connectors_routes.py b/surfsense_backend/app/routes/search_source_connectors_routes.py
index b73b8c789..439d83ac1 100644
--- a/surfsense_backend/app/routes/search_source_connectors_routes.py
+++ b/surfsense_backend/app/routes/search_source_connectors_routes.py
@@ -20,6 +20,7 @@ Non-OAuth connectors (BookStack, GitHub, etc.) are limited to one per search spa
 
 import asyncio
 import logging
+import os
 from contextlib import suppress
 from datetime import UTC, datetime, timedelta
 from typing import Any
@@ -55,23 +56,12 @@ from app.schemas import (
 )
 from app.services.composio_service import ComposioService, get_composio_service
 from app.services.notification_service import NotificationService
-from app.tasks.connector_indexers import (
-    index_airtable_records,
-    index_clickup_tasks,
-    index_confluence_pages,
-    index_crawled_urls,
-    index_discord_messages,
-    index_elasticsearch_documents,
-    index_github_repos,
-    index_google_calendar_events,
-    index_google_gmail_messages,
-    index_jira_issues,
-    index_linear_issues,
-    index_luma_events,
-    index_notion_pages,
-    index_slack_messages,
-)
 from app.users import current_active_user
+
+# NOTE: connector indexer functions are imported lazily inside each
+# ``run_*_indexing`` helper to break a circular import cycle:
+#   connector_indexers.__init__ → airtable_indexer → airtable_history
+#   → app.routes.__init__ → this file → connector_indexers (not ready yet)
 from app.utils.connector_naming import ensure_unique_connector_name
 from app.utils.indexing_locks import (
     acquire_connector_indexing_lock,
@@ -1180,6 +1170,24 @@ async def index_connector_content(
             )
             response_message = "Obsidian vault indexing started in the background."
 
+        elif connector.connector_type == SearchSourceConnectorType.LOCAL_FOLDER_CONNECTOR:
+            from app.config import config as app_config
+            from app.tasks.celery_tasks.connector_tasks import index_local_folder_task
+
+            if not app_config.is_self_hosted():
+                raise HTTPException(
+                    status_code=400,
+                    detail="Local folder connector is only available in self-hosted mode",
+                )
+
+            logger.info(
+                f"Triggering local folder indexing for connector {connector_id} into search space {search_space_id}"
+            )
+            index_local_folder_task.delay(
+                connector_id, search_space_id, str(user.id), indexing_from, indexing_to
+            )
+            response_message = "Local folder indexing started in the background."
+
         elif (
             connector.connector_type
             == SearchSourceConnectorType.COMPOSIO_GOOGLE_DRIVE_CONNECTOR
@@ -1312,6 +1320,76 @@ async def index_connector_content(
         ) from e
 
 
+class IndexFileRequest(BaseModel):
+    file_path: str = Field(..., description="Absolute path to the file to index")
+
+
+@router.post(
+    "/search-source-connectors/{connector_id}/index-file",
+    response_model=dict[str, Any],
+)
+async def index_single_file(
+    connector_id: int,
+    body: IndexFileRequest,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Index a single file from a local folder connector (chokidar real-time trigger)."""
+    from app.config import config as app_config
+    from app.tasks.celery_tasks.connector_tasks import index_local_folder_task
+
+    if not app_config.is_self_hosted():
+        raise HTTPException(
+            status_code=400,
+            detail="Local folder connector is only available in self-hosted mode",
+        )
+
+    result = await session.execute(
+        select(SearchSourceConnector).filter(
+            SearchSourceConnector.id == connector_id,
+            SearchSourceConnector.connector_type
+            == SearchSourceConnectorType.LOCAL_FOLDER_CONNECTOR,
+        )
+    )
+    connector = result.scalars().first()
+    if not connector:
+        raise HTTPException(status_code=404, detail="Local folder connector not found")
+
+    await check_permission(session, user, connector.search_space_id, Permission.WRITE)
+
+    folder_path = connector.config.get("folder_path", "")
+
+    # Security: resolve symlinks and verify the file is inside folder_path
+    try:
+        resolved_file = os.path.realpath(body.file_path)
+        resolved_folder = os.path.realpath(folder_path)
+        if not resolved_file.startswith(resolved_folder + os.sep) and resolved_file != resolved_folder:
+            raise HTTPException(
+                status_code=403,
+                detail="File path is outside the configured folder",
+            )
+    except (OSError, ValueError):
+        raise HTTPException(
+            status_code=403,
+            detail="Invalid file path",
+        )
+
+    index_local_folder_task.delay(
+        connector_id,
+        connector.search_space_id,
+        str(user.id),
+        None,
+        None,
+        target_file_path=resolved_file,
+    )
+
+    return {
+        "message": "Single file indexing started",
+        "connector_id": connector_id,
+        "file_path": body.file_path,
+    }
+
+
 async def _update_connector_timestamp_by_id(session: AsyncSession, connector_id: int):
     """
     Update the last_indexed_at timestamp for a connector by its ID.
@@ -1378,6 +1456,8 @@ async def run_slack_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_slack_messages
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -1824,6 +1904,8 @@ async def run_notion_indexing_with_new_session(
     Create a new session and run the Notion indexing task.
     This prevents session leaks by creating a dedicated session for the background task.
     """
+    from app.tasks.connector_indexers import index_notion_pages
+
     async with async_session_maker() as session:
         await _run_indexing_with_notifications(
             session=session,
@@ -1858,6 +1940,8 @@ async def run_notion_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_notion_pages
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -1910,6 +1994,8 @@ async def run_github_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_github_repos
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -1961,6 +2047,8 @@ async def run_linear_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_linear_issues
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -2011,6 +2099,8 @@ async def run_discord_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_discord_messages
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -2113,6 +2203,8 @@ async def run_jira_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_jira_issues
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -2166,6 +2258,8 @@ async def run_confluence_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_confluence_pages
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -2217,6 +2311,8 @@ async def run_clickup_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_clickup_tasks
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -2268,6 +2364,8 @@ async def run_airtable_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_airtable_records
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -2321,6 +2419,8 @@ async def run_google_calendar_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_google_calendar_events
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -2370,6 +2470,7 @@ async def run_google_gmail_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_google_gmail_messages
 
     # Create a wrapper function that calls index_google_gmail_messages with max_messages
     async def gmail_indexing_wrapper(
@@ -2836,6 +2937,8 @@ async def run_luma_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_luma_events
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -2888,6 +2991,8 @@ async def run_elasticsearch_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_elasticsearch_documents
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -2938,6 +3043,8 @@ async def run_web_page_indexing(
         start_date: Start date for indexing
         end_date: End date for indexing
     """
+    from app.tasks.connector_indexers import index_crawled_urls
+
     await _run_indexing_with_notifications(
         session=session,
         connector_id=connector_id,
@@ -3059,6 +3166,62 @@ async def run_obsidian_indexing(
     )
 
 
+async def run_local_folder_indexing_with_new_session(
+    connector_id: int,
+    search_space_id: int,
+    user_id: str,
+    start_date: str,
+    end_date: str,
+    target_file_path: str | None = None,
+):
+    """Wrapper to run local folder indexing with its own database session."""
+    logger.info(
+        f"Background task started: Indexing local folder connector {connector_id} into space {search_space_id}"
+    )
+    async with async_session_maker() as session:
+        await run_local_folder_indexing(
+            session, connector_id, search_space_id, user_id, start_date, end_date,
+            target_file_path=target_file_path,
+        )
+    logger.info(f"Background task finished: Indexing local folder connector {connector_id}")
+
+
+async def run_local_folder_indexing(
+    session: AsyncSession,
+    connector_id: int,
+    search_space_id: int,
+    user_id: str,
+    start_date: str,
+    end_date: str,
+    target_file_path: str | None = None,
+):
+    """Background task to run local folder indexing."""
+    from app.tasks.connector_indexers import index_local_folder
+
+    await _run_indexing_with_notifications(
+        session=session,
+        connector_id=connector_id,
+        search_space_id=search_space_id,
+        user_id=user_id,
+        start_date=start_date,
+        end_date=end_date,
+        indexing_function=lambda session, connector_id, search_space_id, user_id,
+        start_date, end_date, update_last_indexed, on_heartbeat_callback: index_local_folder(
+            session=session,
+            connector_id=connector_id,
+            search_space_id=search_space_id,
+            user_id=user_id,
+            start_date=start_date,
+            end_date=end_date,
+            update_last_indexed=update_last_indexed,
+            on_heartbeat_callback=on_heartbeat_callback,
+            target_file_path=target_file_path,
+        ),
+        update_timestamp_func=_update_connector_timestamp_by_id,
+        supports_heartbeat_callback=True,
+    )
+
+
 async def run_composio_indexing_with_new_session(
     connector_id: int,
     search_space_id: int,

From fe6c2e9b525be5b29cd9b2ec53ea0b5ea463f95f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 10:37:05 +0530
Subject: [PATCH 13/70] chore: add electron-store dependency for persistent
 data storage

---
 surfsense_desktop/package.json   |   1 +
 surfsense_desktop/pnpm-lock.yaml | 151 ++++++++++++++++++++++++++++++-
 2 files changed, 151 insertions(+), 1 deletion(-)

diff --git a/surfsense_desktop/package.json b/surfsense_desktop/package.json
index 5bbd50514..21e7f4bea 100644
--- a/surfsense_desktop/package.json
+++ b/surfsense_desktop/package.json
@@ -28,6 +28,7 @@
   },
   "dependencies": {
     "chokidar": "^5.0.0",
+    "electron-store": "^11.0.2",
     "electron-updater": "^6.8.3",
     "get-port-please": "^3.2.0"
   }
diff --git a/surfsense_desktop/pnpm-lock.yaml b/surfsense_desktop/pnpm-lock.yaml
index 1533803fb..528f81539 100644
--- a/surfsense_desktop/pnpm-lock.yaml
+++ b/surfsense_desktop/pnpm-lock.yaml
@@ -11,6 +11,9 @@ importers:
       chokidar:
         specifier: ^5.0.0
         version: 5.0.0
+      electron-store:
+        specifier: ^11.0.2
+        version: 11.0.2
       electron-updater:
         specifier: ^6.8.3
         version: 6.8.3
@@ -355,6 +358,14 @@ packages:
     resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
     engines: {node: '>= 14'}
 
+  ajv-formats@3.0.1:
+    resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==}
+    peerDependencies:
+      ajv: ^8.0.0
+    peerDependenciesMeta:
+      ajv:
+        optional: true
+
   ajv-keywords@3.5.2:
     resolution: {integrity: sha512-5p6WTN0DdTGVQk6VjcEju19IgaHudalcfabD7yhDGeA6bcQnmL+CpveLJq/3hvfwd1aof6L386Ougkx6RfyMIQ==}
     peerDependencies:
@@ -363,6 +374,9 @@ packages:
   ajv@6.14.0:
     resolution: {integrity: sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==}
 
+  ajv@8.18.0:
+    resolution: {integrity: sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==}
+
   ansi-regex@5.0.1:
     resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
     engines: {node: '>=8'}
@@ -414,6 +428,9 @@ packages:
     resolution: {integrity: sha512-+q/t7Ekv1EDY2l6Gda6LLiX14rU9TV20Wa3ofeQmwPFZbOMo9DXrLbOjFaaclkXKWidIaopwAObQDqwWtGUjqg==}
     engines: {node: '>= 4.0.0'}
 
+  atomically@2.1.1:
+    resolution: {integrity: sha512-P4w9o2dqARji6P7MHprklbfiArZAWvo07yW7qs3pdljb3BWr12FIB7W+p0zJiuiVsUpRO0iZn1kFFcpPegg0tQ==}
+
   axios@1.13.6:
     resolution: {integrity: sha512-ChTCHMouEe2kn713WHbQGcuYrr6fXTBiu460OTwWrWob16g1bXn4vtz07Ope7ewMozJAnEquLk5lWQWtBig9DQ==}
 
@@ -553,6 +570,10 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  conf@15.1.0:
+    resolution: {integrity: sha512-Uy5YN9KEu0WWDaZAVJ5FAmZoaJt9rdK6kH+utItPyGsCqCgaTKkrmZx3zoE0/3q6S3bcp3Ihkk+ZqPxWxFK5og==}
+    engines: {node: '>=20'}
+
   core-util-is@1.0.2:
     resolution: {integrity: sha512-3lqz5YjWTYnW6dlDa5TLaTCcShfar1e40rmcJVwCBJC6mWlFuj0eCHIElmG1g5kyuJ/GD+8Wn4FFCcz4gJPfaQ==}
 
@@ -566,6 +587,10 @@ packages:
     resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
     engines: {node: '>= 8'}
 
+  debounce-fn@6.0.0:
+    resolution: {integrity: sha512-rBMW+F2TXryBwB54Q0d8drNEI+TfoS9JpNTAoVpukbWEhjXQq4rySFYLaqXMFXwdv61Zb2OHtj5bviSoimqxRQ==}
+    engines: {node: '>=18'}
+
   debug@4.4.3:
     resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
     engines: {node: '>=6.0'}
@@ -617,6 +642,10 @@ packages:
     os: [darwin]
     hasBin: true
 
+  dot-prop@10.1.0:
+    resolution: {integrity: sha512-MVUtAugQMOff5RnBy2d9N31iG0lNwg1qAoAOn7pOK5wf94WIaE3My2p3uwTQuvS2AcqchkcR3bHByjaM0mmi7Q==}
+    engines: {node: '>=20'}
+
   dotenv-expand@11.0.7:
     resolution: {integrity: sha512-zIHwmZPRshsCdpMDyVsqGmgyP0yT8GAgXUnkdAoJisxvf33k7yO6OuoKmcTGuXPWSsm8Oh88nZicRLA9Y0rUeA==}
     engines: {node: '>=12'}
@@ -652,6 +681,10 @@ packages:
   electron-publish@26.8.1:
     resolution: {integrity: sha512-q+jrSTIh/Cv4eGZa7oVR+grEJo/FoLMYBAnSL5GCtqwUpr1T+VgKB/dn1pnzxIxqD8S/jP1yilT9VrwCqINR4w==}
 
+  electron-store@11.0.2:
+    resolution: {integrity: sha512-4VkNRdN+BImL2KcCi41WvAYbh6zLX5AUTi4so68yPqiItjbgTjqpEnGAqasgnG+lB6GuAyUltKwVopp6Uv+gwQ==}
+    engines: {node: '>=20'}
+
   electron-updater@6.8.3:
     resolution: {integrity: sha512-Z6sgw3jgbikWKXei1ENdqFOxBP0WlXg3TtKfz0rgw2vIZFJUyI4pD7ZN7jrkm7EoMK+tcm/qTnPUdqfZukBlBQ==}
 
@@ -680,6 +713,10 @@ packages:
     resolution: {integrity: sha512-+h1lkLKhZMTYjog1VEpJNG7NZJWcuc2DDk/qsqSTRRCOXiLjeQ1d1/udrUGhqMxUgAlwKNZ0cf2uqan5GLuS2A==}
     engines: {node: '>=6'}
 
+  env-paths@3.0.0:
+    resolution: {integrity: sha512-dtJUTepzMW3Lm/NPxRf3wP4642UWhjL2sQxc+ym2YMj1m/H2zDNQOlezafzkHwn6sMstjHTwG6iQQsctDW/b1A==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
   err-code@2.0.3:
     resolution: {integrity: sha512-2bmlRpNKBxT/CRmPOlyISQpNj+qSeYvcym/uT0Jx2bMOlKLtSy1ZmLuVxSEKKyor/N5yhvp/ZiG1oE3DEYMSFA==}
 
@@ -733,6 +770,9 @@ packages:
   fast-json-stable-stringify@2.1.0:
     resolution: {integrity: sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==}
 
+  fast-uri@3.1.0:
+    resolution: {integrity: sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==}
+
   fd-slicer@1.1.0:
     resolution: {integrity: sha512-cE1qsB/VwyQozZ+q1dGxR8LBYNZeofhEdUNGSMbQD3Gw2lAzX9Zb3uIU6Ebc/Fmyjo9AWWfnn0AUCHqtevs/8g==}
 
@@ -960,6 +1000,12 @@ packages:
   json-schema-traverse@0.4.1:
     resolution: {integrity: sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==}
 
+  json-schema-traverse@1.0.0:
+    resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+
+  json-schema-typed@8.0.2:
+    resolution: {integrity: sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==}
+
   json-stringify-safe@5.0.1:
     resolution: {integrity: sha512-ZClg6AaYvamvYEE82d3Iyd3vSSIjQ+odgjaTzRuO3s7toCdFKczob2i0zCh7JE8kWn17yvAWhUVxvqGwUalsRA==}
 
@@ -990,6 +1036,9 @@ packages:
   lodash@4.17.23:
     resolution: {integrity: sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==}
 
+  lodash@4.18.1:
+    resolution: {integrity: sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==}
+
   log-symbols@4.1.0:
     resolution: {integrity: sha512-8XPvpAA8uyhfteu8pIvQxpJZ7SYYdpUivZpGy6sFsBuKRY/7rQGavedeB8aK+Zkyq6upMFVL/9AW6vOYzfRyLg==}
     engines: {node: '>=10'}
@@ -1034,6 +1083,10 @@ packages:
     resolution: {integrity: sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==}
     engines: {node: '>=6'}
 
+  mimic-function@5.0.1:
+    resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
+    engines: {node: '>=18'}
+
   mimic-response@1.0.1:
     resolution: {integrity: sha512-j5EctnkH7amfV/q5Hgmoal1g2QHFJRraOtmx0JpIqkxhBhI/lJSl1nMpQ45hVarwNETOoWEimndZ4QK0RHxuxQ==}
     engines: {node: '>=4'}
@@ -1237,6 +1290,10 @@ packages:
     resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
     engines: {node: '>=0.10.0'}
 
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+    engines: {node: '>=0.10.0'}
+
   resedit@1.7.2:
     resolution: {integrity: sha512-vHjcY2MlAITJhC0eRD/Vv8Vlgmu9Sd3LX9zZvtGzU5ZImdTN3+d6e/4mnTyV8vEbyf1sgNIrWxhWlrys52OkEA==}
     engines: {node: '>=12', npm: '>=6'}
@@ -1376,6 +1433,12 @@ packages:
     resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
     engines: {node: '>=12'}
 
+  stubborn-fs@2.0.0:
+    resolution: {integrity: sha512-Y0AvSwDw8y+nlSNFXMm2g6L51rBGdAQT20J3YSOqxC53Lo3bjWRtr2BKcfYoAf352WYpsZSTURrA0tqhfgudPA==}
+
+  stubborn-utils@1.0.2:
+    resolution: {integrity: sha512-zOh9jPYI+xrNOyisSelgym4tolKTJCQd5GBhK0+0xJvcYDcwlOoxF/rnFKQ2KRZknXSG9jWAp66fwP6AxN9STg==}
+
   sumchecker@3.0.1:
     resolution: {integrity: sha512-MvjXzkz/BOfyVDkG0oFOtBxHX2u3gKbMHIF/dXblZsgD3BWOFLmHovIpZY7BykJdAjcqRCBi1WYBNdEC9yI7vg==}
     engines: {node: '>= 8.0'}
@@ -1388,6 +1451,10 @@ packages:
     resolution: {integrity: sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==}
     engines: {node: '>=10'}
 
+  tagged-tag@1.0.0:
+    resolution: {integrity: sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==}
+    engines: {node: '>=20'}
+
   tar@7.5.11:
     resolution: {integrity: sha512-ChjMH33/KetonMTAtpYdgUFr0tbz69Fp2v7zWxQfYZX4g5ZN2nOBXm1R2xyA+lMIKrLKIoKAwFj93jE/avX9cQ==}
     engines: {node: '>=18'}
@@ -1430,11 +1497,19 @@ packages:
     resolution: {integrity: sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg==}
     engines: {node: '>=10'}
 
+  type-fest@5.5.0:
+    resolution: {integrity: sha512-PlBfpQwiUvGViBNX84Yxwjsdhd1TUlXr6zjX7eoirtCPIr08NAmxwa+fcYBTeRQxHo9YC9wwF3m9i700sHma8g==}
+    engines: {node: '>=20'}
+
   typescript@5.9.3:
     resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
     engines: {node: '>=14.17'}
     hasBin: true
 
+  uint8array-extras@1.5.0:
+    resolution: {integrity: sha512-rvKSBiC5zqCCiDZ9kAOszZcDvdAHwwIKJG33Ykj43OKcWsnmcBRL09YTU4nOeHZ8Y2a7l1MgTd08SBe9A8Qj6A==}
+    engines: {node: '>=18'}
+
   undici-types@7.16.0:
     resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
 
@@ -1478,6 +1553,9 @@ packages:
   wcwidth@1.0.1:
     resolution: {integrity: sha512-XHPEwS0q6TaxcvG85+8EYkbiCux2XtWG2mkc47Ng2A77BQu9+DqIOJldST4HgPkuea7dvKSj5VgX3P1d4rW8Tg==}
 
+  when-exit@2.1.5:
+    resolution: {integrity: sha512-VGkKJ564kzt6Ms1dbgPP/yuIoQCrsFAnRbptpC5wOEsDaNsbCB2bnfnaA8i/vRs5tjUSEOtIuvl9/MyVsvQZCg==}
+
   which@2.0.2:
     resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
     engines: {node: '>= 8'}
@@ -1838,6 +1916,10 @@ snapshots:
 
   agent-base@7.1.4: {}
 
+  ajv-formats@3.0.1(ajv@8.18.0):
+    optionalDependencies:
+      ajv: 8.18.0
+
   ajv-keywords@3.5.2(ajv@6.14.0):
     dependencies:
       ajv: 6.14.0
@@ -1849,6 +1931,13 @@ snapshots:
       json-schema-traverse: 0.4.1
       uri-js: 4.4.1
 
+  ajv@8.18.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-uri: 3.1.0
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+
   ansi-regex@5.0.1: {}
 
   ansi-regex@6.2.2: {}
@@ -1920,6 +2009,11 @@ snapshots:
 
   at-least-node@1.0.0: {}
 
+  atomically@2.1.1:
+    dependencies:
+      stubborn-fs: 2.0.0
+      when-exit: 2.1.5
+
   axios@1.13.6:
     dependencies:
       follow-redirects: 1.15.11
@@ -2094,6 +2188,18 @@ snapshots:
       tree-kill: 1.2.2
       yargs: 17.7.2
 
+  conf@15.1.0:
+    dependencies:
+      ajv: 8.18.0
+      ajv-formats: 3.0.1(ajv@8.18.0)
+      atomically: 2.1.1
+      debounce-fn: 6.0.0
+      dot-prop: 10.1.0
+      env-paths: 3.0.0
+      json-schema-typed: 8.0.2
+      semver: 7.7.4
+      uint8array-extras: 1.5.0
+
   core-util-is@1.0.2:
     optional: true
 
@@ -2111,6 +2217,10 @@ snapshots:
       shebang-command: 2.0.0
       which: 2.0.2
 
+  debounce-fn@6.0.0:
+    dependencies:
+      mimic-function: 5.0.1
+
   debug@4.4.3:
     dependencies:
       ms: 2.1.3
@@ -2176,6 +2286,10 @@ snapshots:
       verror: 1.10.1
     optional: true
 
+  dot-prop@10.1.0:
+    dependencies:
+      type-fest: 5.5.0
+
   dotenv-expand@11.0.7:
     dependencies:
       dotenv: 16.6.1
@@ -2234,6 +2348,11 @@ snapshots:
     transitivePeerDependencies:
       - supports-color
 
+  electron-store@11.0.2:
+    dependencies:
+      conf: 15.1.0
+      type-fest: 5.5.0
+
   electron-updater@6.8.3:
     dependencies:
       builder-util-runtime: 9.5.1
@@ -2252,7 +2371,7 @@ snapshots:
       '@electron/asar': 3.4.1
       debug: 4.4.3
       fs-extra: 7.0.1
-      lodash: 4.17.23
+      lodash: 4.18.1
       temp: 0.9.4
     optionalDependencies:
       '@electron/windows-sign': 1.2.2
@@ -2282,6 +2401,8 @@ snapshots:
 
   env-paths@2.2.1: {}
 
+  env-paths@3.0.0: {}
+
   err-code@2.0.3: {}
 
   es-define-property@1.0.1: {}
@@ -2355,6 +2476,8 @@ snapshots:
 
   fast-json-stable-stringify@2.1.0: {}
 
+  fast-uri@3.1.0: {}
+
   fd-slicer@1.1.0:
     dependencies:
       pend: 1.2.0
@@ -2610,6 +2733,10 @@ snapshots:
 
   json-schema-traverse@0.4.1: {}
 
+  json-schema-traverse@1.0.0: {}
+
+  json-schema-typed@8.0.2: {}
+
   json-stringify-safe@5.0.1:
     optional: true
 
@@ -2637,6 +2764,8 @@ snapshots:
 
   lodash@4.17.23: {}
 
+  lodash@4.18.1: {}
+
   log-symbols@4.1.0:
     dependencies:
       chalk: 4.1.2
@@ -2683,6 +2812,8 @@ snapshots:
 
   mimic-fn@2.1.0: {}
 
+  mimic-function@5.0.1: {}
+
   mimic-response@1.0.1: {}
 
   mimic-response@3.1.0: {}
@@ -2882,6 +3013,8 @@ snapshots:
 
   require-directory@2.1.1: {}
 
+  require-from-string@2.0.2: {}
+
   resedit@1.7.2:
     dependencies:
       pe-library: 0.4.1
@@ -3019,6 +3152,12 @@ snapshots:
     dependencies:
       ansi-regex: 6.2.2
 
+  stubborn-fs@2.0.0:
+    dependencies:
+      stubborn-utils: 1.0.2
+
+  stubborn-utils@1.0.2: {}
+
   sumchecker@3.0.1:
     dependencies:
       debug: 4.4.3
@@ -3033,6 +3172,8 @@ snapshots:
     dependencies:
       has-flag: 4.0.0
 
+  tagged-tag@1.0.0: {}
+
   tar@7.5.11:
     dependencies:
       '@isaacs/fs-minipass': 4.0.1
@@ -3079,8 +3220,14 @@ snapshots:
   type-fest@0.13.1:
     optional: true
 
+  type-fest@5.5.0:
+    dependencies:
+      tagged-tag: 1.0.0
+
   typescript@5.9.3: {}
 
+  uint8array-extras@1.5.0: {}
+
   undici-types@7.16.0: {}
 
   undici-types@7.18.2: {}
@@ -3126,6 +3273,8 @@ snapshots:
     dependencies:
       defaults: 1.0.4
 
+  when-exit@2.1.5: {}
+
   which@2.0.2:
     dependencies:
       isexe: 2.0.0

From 96a58d0d30fa9ff169ace3e005757becfef16261 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 11:11:57 +0530
Subject: [PATCH 14/70] feat: implement local folder indexing and document
 versioning capabilities

---
 .../app/tasks/celery_tasks/connector_tasks.py |  46 +
 .../app/tasks/connector_indexers/__init__.py  |   4 +-
 .../local_folder_indexer.py                   | 971 ++++++++++++++++++
 .../app/utils/document_versioning.py          | 107 ++
 4 files changed, 1127 insertions(+), 1 deletion(-)
 create mode 100644 surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
 create mode 100644 surfsense_backend/app/utils/document_versioning.py

diff --git a/surfsense_backend/app/tasks/celery_tasks/connector_tasks.py b/surfsense_backend/app/tasks/celery_tasks/connector_tasks.py
index 57475c9fd..9ff578ad2 100644
--- a/surfsense_backend/app/tasks/celery_tasks/connector_tasks.py
+++ b/surfsense_backend/app/tasks/celery_tasks/connector_tasks.py
@@ -926,6 +926,52 @@ async def _index_obsidian_vault(
         )
 
 
+@celery_app.task(name="index_local_folder", bind=True)
+def index_local_folder_task(
+    self,
+    connector_id: int,
+    search_space_id: int,
+    user_id: str,
+    start_date: str = None,
+    end_date: str = None,
+    target_file_path: str = None,
+):
+    """Celery task to index a local folder."""
+    import asyncio
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    try:
+        loop.run_until_complete(
+            _index_local_folder(
+                connector_id, search_space_id, user_id, start_date, end_date, target_file_path
+            )
+        )
+    finally:
+        loop.close()
+
+
+async def _index_local_folder(
+    connector_id: int,
+    search_space_id: int,
+    user_id: str,
+    start_date: str = None,
+    end_date: str = None,
+    target_file_path: str = None,
+):
+    """Index local folder with new session."""
+    from app.routes.search_source_connectors_routes import (
+        run_local_folder_indexing,
+    )
+
+    async with get_celery_session_maker()() as session:
+        await run_local_folder_indexing(
+            session, connector_id, search_space_id, user_id, start_date, end_date,
+            target_file_path=target_file_path,
+        )
+
+
 @celery_app.task(name="index_composio_connector", bind=True)
 def index_composio_connector_task(
     self,
diff --git a/surfsense_backend/app/tasks/connector_indexers/__init__.py b/surfsense_backend/app/tasks/connector_indexers/__init__.py
index 9a1d17fd5..8e4ad69e5 100644
--- a/surfsense_backend/app/tasks/connector_indexers/__init__.py
+++ b/surfsense_backend/app/tasks/connector_indexers/__init__.py
@@ -42,9 +42,10 @@ from .jira_indexer import index_jira_issues
 
 # Issue tracking and project management
 from .linear_indexer import index_linear_issues
-from .luma_indexer import index_luma_events
 
 # Documentation and knowledge management
+from .local_folder_indexer import index_local_folder
+from .luma_indexer import index_luma_events
 from .notion_indexer import index_notion_pages
 from .obsidian_indexer import index_obsidian_vault
 from .slack_indexer import index_slack_messages
@@ -74,4 +75,5 @@ __all__ = [  # noqa: RUF022
     # Communication platforms
     "index_slack_messages",
     "index_google_gmail_messages",
+    "index_local_folder",
 ]
diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
new file mode 100644
index 000000000..fc7fdaf66
--- /dev/null
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -0,0 +1,971 @@
+"""
+Local folder connector indexer.
+
+Indexes files from a local folder on disk. Supports:
+- Full-scan mode (startup reconciliation / manual trigger)
+- Single-file mode (chokidar real-time trigger)
+- Filesystem folder structure mirroring into DB Folder rows
+- Document versioning via create_version_snapshot
+- ETL-based file parsing for binary formats (PDF, DOCX, images, audio, etc.)
+
+Electron-only: all change detection is driven by chokidar in the desktop app.
+"""
+
+import os
+import time
+from collections.abc import Awaitable, Callable
+from datetime import UTC, datetime
+from pathlib import Path
+
+from sqlalchemy import delete, select
+from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm.attributes import flag_modified
+
+from app.config import config
+from app.db import (
+    Document,
+    DocumentStatus,
+    DocumentType,
+    Folder,
+    SearchSourceConnectorType,
+)
+from app.services.llm_service import get_user_long_context_llm
+from app.services.task_logging_service import TaskLoggingService
+from app.utils.document_converters import (
+    create_document_chunks,
+    embed_text,
+    generate_content_hash,
+    generate_document_summary,
+    generate_unique_identifier_hash,
+)
+from app.utils.document_versioning import create_version_snapshot
+
+from .base import (
+    build_document_metadata_string,
+    check_document_by_unique_identifier,
+    check_duplicate_document_by_hash,
+    get_connector_by_id,
+    get_current_timestamp,
+    logger,
+    safe_set_chunks,
+    update_connector_last_indexed,
+)
+
+PLAINTEXT_EXTENSIONS = frozenset({
+    ".md", ".markdown", ".txt", ".text", ".csv", ".tsv",
+    ".json", ".jsonl", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf",
+    ".xml", ".html", ".htm", ".css", ".scss", ".less", ".sass",
+    ".py", ".pyw", ".pyi", ".pyx",
+    ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
+    ".java", ".kt", ".kts", ".scala", ".groovy",
+    ".c", ".h", ".cpp", ".cxx", ".cc", ".hpp", ".hxx",
+    ".cs", ".fs", ".fsx",
+    ".go", ".rs", ".rb", ".php", ".pl", ".pm", ".lua",
+    ".swift", ".m", ".mm",
+    ".r", ".R", ".jl",
+    ".sh", ".bash", ".zsh", ".fish", ".bat", ".cmd", ".ps1",
+    ".sql", ".graphql", ".gql",
+    ".env", ".gitignore", ".dockerignore", ".editorconfig",
+    ".makefile", ".cmake",
+    ".log", ".rst", ".tex", ".bib", ".org", ".adoc", ".asciidoc",
+    ".vue", ".svelte", ".astro",
+    ".tf", ".hcl", ".proto",
+})
+
+AUDIO_EXTENSIONS = frozenset({
+    ".mp3", ".mp4", ".mpeg", ".mpga", ".m4a", ".wav", ".webm",
+})
+
+
+def _is_plaintext_file(filename: str) -> bool:
+    return Path(filename).suffix.lower() in PLAINTEXT_EXTENSIONS
+
+
+def _is_audio_file(filename: str) -> bool:
+    return Path(filename).suffix.lower() in AUDIO_EXTENSIONS
+
+
+def _needs_etl(filename: str) -> bool:
+    """File is not plaintext and not audio — requires ETL service to parse."""
+    return not _is_plaintext_file(filename) and not _is_audio_file(filename)
+
+HeartbeatCallbackType = Callable[[int], Awaitable[None]]
+HEARTBEAT_INTERVAL_SECONDS = 30
+
+DEFAULT_EXCLUDE_PATTERNS = [
+    ".git",
+    "node_modules",
+    "__pycache__",
+    ".DS_Store",
+    ".obsidian",
+    ".trash",
+]
+
+
+def scan_folder(
+    folder_path: str,
+    file_extensions: list[str] | None = None,
+    exclude_patterns: list[str] | None = None,
+) -> list[dict]:
+    """Walk a directory and return a list of file entries.
+
+    Args:
+        folder_path: Absolute path to the folder to scan.
+        file_extensions: If provided, only include files with these extensions
+            (e.g. [".md", ".txt"]). ``None`` means include all files.
+        exclude_patterns: Directory/file names to exclude.  Any path component
+            matching one of these strings is skipped.
+
+    Returns:
+        List of dicts with keys: path, relative_path, name, modified_at, size.
+    """
+    root = Path(folder_path)
+    if not root.exists():
+        raise ValueError(f"Folder path does not exist: {folder_path}")
+
+    if exclude_patterns is None:
+        exclude_patterns = []
+
+    files: list[dict] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        rel_dir = Path(dirpath).relative_to(root)
+
+        # Prune excluded directories in-place so os.walk skips them
+        dirnames[:] = [
+            d for d in dirnames if d not in exclude_patterns
+        ]
+
+        # Check if the current directory itself is excluded
+        if any(part in exclude_patterns for part in rel_dir.parts):
+            continue
+
+        for fname in filenames:
+            if fname in exclude_patterns:
+                continue
+
+            full = Path(dirpath) / fname
+
+            if file_extensions is not None:
+                if full.suffix.lower() not in file_extensions:
+                    continue
+
+            try:
+                stat = full.stat()
+                rel_path = full.relative_to(root)
+                files.append(
+                    {
+                        "path": str(full),
+                        "relative_path": str(rel_path),
+                        "name": full.name,
+                        "modified_at": datetime.fromtimestamp(stat.st_mtime, tz=UTC),
+                        "size": stat.st_size,
+                    }
+                )
+            except OSError as e:
+                logger.warning(f"Could not stat file {full}: {e}")
+
+    return files
+
+
+def _read_plaintext_file(file_path: str) -> str:
+    """Read a plaintext/text-based file as UTF-8."""
+    with open(file_path, encoding="utf-8", errors="replace") as f:
+        content = f.read()
+    if "\x00" in content:
+        raise ValueError(
+            f"File contains null bytes — likely a binary file opened as text: {file_path}"
+        )
+    return content
+
+
+async def _read_file_content(file_path: str, filename: str) -> str:
+    """Read file content, using ETL for binary formats.
+
+    Plaintext files are read directly. Audio and document files (PDF, DOCX, etc.)
+    are routed through the configured ETL service (same as Google Drive / OneDrive).
+
+    Raises ValueError if the file cannot be parsed (e.g. no ETL service configured
+    for a binary file).
+    """
+    if _is_plaintext_file(filename):
+        return _read_plaintext_file(file_path)
+
+    if _is_audio_file(filename):
+        etl_service = config.ETL_SERVICE if hasattr(config, "ETL_SERVICE") else None
+        stt_service_val = config.STT_SERVICE if hasattr(config, "STT_SERVICE") else None
+        if not stt_service_val and not etl_service:
+            raise ValueError(
+                f"No STT_SERVICE configured — cannot transcribe audio file: {filename}"
+            )
+
+    if _needs_etl(filename):
+        etl_service = getattr(config, "ETL_SERVICE", None)
+        if not etl_service:
+            raise ValueError(
+                f"No ETL_SERVICE configured — cannot parse binary file: {filename}. "
+                f"Set ETL_SERVICE to UNSTRUCTURED, LLAMACLOUD, or DOCLING in your .env"
+            )
+
+    from app.connectors.onedrive.content_extractor import (
+        _parse_file_to_markdown,
+    )
+
+    return await _parse_file_to_markdown(file_path, filename)
+
+
+async def _compute_file_content_hash(
+    file_path: str, filename: str, search_space_id: int,
+) -> tuple[str, str]:
+    """Read a file (via ETL if needed) and compute its content hash.
+
+    Returns (content_text, content_hash).
+    """
+    content = await _read_file_content(file_path, filename)
+    content_hash = generate_content_hash(content, search_space_id)
+    return content, content_hash
+
+
+async def _mirror_folder_structure(
+    session: AsyncSession,
+    folder_path: str,
+    folder_name: str,
+    search_space_id: int,
+    user_id: str,
+    connector_config: dict,
+    connector,
+    exclude_patterns: list[str] | None = None,
+) -> dict[str, int]:
+    """Mirror the local filesystem directory structure into DB Folder rows.
+
+    Returns a mapping of relative_dir_path -> folder_id.
+    The empty string key ("") maps to the root folder.
+    """
+    root = Path(folder_path)
+    if exclude_patterns is None:
+        exclude_patterns = []
+
+    # Collect all subdirectory paths relative to root
+    subdirs: list[str] = []
+    for dirpath, dirnames, _ in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in exclude_patterns]
+        rel = Path(dirpath).relative_to(root)
+        if any(part in exclude_patterns for part in rel.parts):
+            continue
+        rel_str = str(rel) if str(rel) != "." else ""
+        if rel_str:
+            subdirs.append(rel_str)
+
+    # Sort by depth so parents are created before children
+    subdirs.sort(key=lambda p: p.count(os.sep))
+
+    mapping: dict[str, int] = {}
+
+    # Get or create root folder
+    root_folder_id = connector_config.get("root_folder_id")
+    if root_folder_id:
+        existing = (
+            await session.execute(
+                select(Folder).where(Folder.id == root_folder_id)
+            )
+        ).scalar_one_or_none()
+        if existing:
+            mapping[""] = existing.id
+        else:
+            root_folder_id = None
+
+    if not root_folder_id:
+        root_folder = Folder(
+            name=folder_name,
+            search_space_id=search_space_id,
+            created_by_id=user_id,
+            position="a0",
+        )
+        session.add(root_folder)
+        await session.flush()
+        mapping[""] = root_folder.id
+        # Persist root_folder_id into connector config
+        connector_config["root_folder_id"] = root_folder.id
+        connector.config = {**connector.config, "root_folder_id": root_folder.id}
+        flag_modified(connector, "config")
+
+    # Create/reuse subdirectory Folder rows
+    for rel_dir in subdirs:
+        dir_parts = Path(rel_dir).parts
+        dir_name = dir_parts[-1]
+        parent_rel = str(Path(*dir_parts[:-1])) if len(dir_parts) > 1 else ""
+
+        parent_id = mapping.get(parent_rel, mapping[""])
+
+        existing_folder = (
+            await session.execute(
+                select(Folder).where(
+                    Folder.name == dir_name,
+                    Folder.parent_id == parent_id,
+                    Folder.search_space_id == search_space_id,
+                )
+            )
+        ).scalar_one_or_none()
+
+        if existing_folder:
+            mapping[rel_dir] = existing_folder.id
+        else:
+            new_folder = Folder(
+                name=dir_name,
+                parent_id=parent_id,
+                search_space_id=search_space_id,
+                created_by_id=user_id,
+                position="a0",
+            )
+            session.add(new_folder)
+            await session.flush()
+            mapping[rel_dir] = new_folder.id
+
+    await session.flush()
+    return mapping
+
+
+async def _cleanup_empty_folders(
+    session: AsyncSession,
+    root_folder_id: int,
+    search_space_id: int,
+    existing_dirs_on_disk: set[str],
+    folder_mapping: dict[str, int],
+) -> None:
+    """Delete Folder rows that are empty (no docs, no children) and no longer on disk.
+
+    Queries ALL folders under this search space (not just the current mapping)
+    so that stale folders from previous syncs are also cleaned up.
+    """
+    # Build a reverse mapping from folder_id → rel_dir for known dirs
+    id_to_rel: dict[int, str] = {fid: rel for rel, fid in folder_mapping.items() if rel}
+
+    # Also find any folders in the DB that are children of the root but NOT
+    # in the current mapping (stale from a previous sync).
+    all_folders = (
+        await session.execute(
+            select(Folder).where(
+                Folder.search_space_id == search_space_id,
+                Folder.id != root_folder_id,
+            )
+        )
+    ).scalars().all()
+
+    # Build candidates: folders not on disk that we might delete
+    candidates: list[Folder] = []
+    for folder in all_folders:
+        rel = id_to_rel.get(folder.id)
+        if rel and rel in existing_dirs_on_disk:
+            continue
+        candidates.append(folder)
+
+    # Sort deepest first (by name depth heuristic — folders with no children first)
+    # Repeat until no more deletions happen (cascading empty parents)
+    changed = True
+    while changed:
+        changed = False
+        remaining: list[Folder] = []
+        for folder in candidates:
+            doc_exists = (
+                await session.execute(
+                    select(Document.id).where(Document.folder_id == folder.id).limit(1)
+                )
+            ).scalar_one_or_none()
+            if doc_exists is not None:
+                remaining.append(folder)
+                continue
+
+            child_exists = (
+                await session.execute(
+                    select(Folder.id).where(Folder.parent_id == folder.id).limit(1)
+                )
+            ).scalar_one_or_none()
+            if child_exists is not None:
+                remaining.append(folder)
+                continue
+
+            await session.execute(delete(Folder).where(Folder.id == folder.id))
+            changed = True
+        candidates = remaining
+
+
+async def index_local_folder(
+    session: AsyncSession,
+    connector_id: int,
+    search_space_id: int,
+    user_id: str,
+    start_date: str | None = None,
+    end_date: str | None = None,
+    update_last_indexed: bool = True,
+    on_heartbeat_callback: HeartbeatCallbackType | None = None,
+    target_file_path: str | None = None,
+) -> tuple[int, int, str | None]:
+    """Index files from a local folder.
+
+    Supports two modes:
+    - Full scan (target_file_path=None): walks entire folder, handles new/changed/deleted files.
+    - Single-file (target_file_path set): processes only that file.
+
+    Returns (indexed_count, skipped_count, error_or_warning_message).
+    """
+    task_logger = TaskLoggingService(session, search_space_id)
+
+    log_entry = await task_logger.log_task_start(
+        task_name="local_folder_indexing",
+        source="connector_indexing_task",
+        message=f"Starting local folder indexing for connector {connector_id}",
+        metadata={
+            "connector_id": connector_id,
+            "user_id": str(user_id),
+            "target_file_path": target_file_path,
+        },
+    )
+
+    try:
+        connector = await get_connector_by_id(
+            session, connector_id, SearchSourceConnectorType.LOCAL_FOLDER_CONNECTOR
+        )
+        if not connector:
+            await task_logger.log_task_failure(
+                log_entry,
+                f"Connector {connector_id} not found",
+                "Connector not found",
+                {},
+            )
+            return 0, 0, f"Connector {connector_id} not found"
+
+        folder_path = connector.config.get("folder_path")
+        if not folder_path or not os.path.exists(folder_path):
+            await task_logger.log_task_failure(
+                log_entry,
+                f"Folder path missing or does not exist: {folder_path}",
+                "Folder not found",
+                {},
+            )
+            return 0, 0, f"Folder path missing or does not exist: {folder_path}"
+
+        folder_name = connector.config.get("folder_name") or os.path.basename(folder_path)
+        exclude_patterns = connector.config.get("exclude_patterns", DEFAULT_EXCLUDE_PATTERNS)
+        file_extensions = connector.config.get("file_extensions")  # None = all
+
+        # ====================================================================
+        # SINGLE-FILE MODE
+        # ====================================================================
+        if target_file_path:
+            return await _index_single_file(
+                session=session,
+                connector=connector,
+                connector_id=connector_id,
+                search_space_id=search_space_id,
+                user_id=user_id,
+                folder_path=folder_path,
+                folder_name=folder_name,
+                target_file_path=target_file_path,
+                task_logger=task_logger,
+                log_entry=log_entry,
+                update_last_indexed=update_last_indexed,
+            )
+
+        # ====================================================================
+        # FULL-SCAN MODE
+        # ====================================================================
+
+        # Phase 0: Mirror folder structure
+        await task_logger.log_task_progress(
+            log_entry, "Mirroring folder structure", {"stage": "folder_mirror"}
+        )
+
+        folder_mapping = await _mirror_folder_structure(
+            session=session,
+            folder_path=folder_path,
+            folder_name=folder_name,
+            search_space_id=search_space_id,
+            user_id=user_id,
+            connector_config=connector.config,
+            connector=connector,
+            exclude_patterns=exclude_patterns,
+        )
+        await session.flush()
+
+        # Scan files on disk
+        try:
+            files = scan_folder(folder_path, file_extensions, exclude_patterns)
+        except Exception as e:
+            await task_logger.log_task_failure(
+                log_entry, f"Failed to scan folder: {e}", "Scan error", {}
+            )
+            return 0, 0, f"Failed to scan folder: {e}"
+
+        logger.info(f"Found {len(files)} files in folder")
+
+        indexed_count = 0
+        skipped_count = 0
+        failed_count = 0
+        duplicate_count = 0
+
+        last_heartbeat_time = time.time()
+
+        # ================================================================
+        # PHASE 1: Analyze all files, create pending documents
+        # ================================================================
+        files_to_process: list[dict] = []
+        new_documents_created = False
+        seen_unique_hashes: set[str] = set()
+
+        for file_info in files:
+            try:
+                relative_path = file_info["relative_path"]
+                file_path_abs = file_info["path"]
+
+                unique_identifier = f"{folder_name}:{relative_path}"
+                unique_identifier_hash = generate_unique_identifier_hash(
+                    DocumentType.LOCAL_FOLDER_FILE,
+                    unique_identifier,
+                    search_space_id,
+                )
+                seen_unique_hashes.add(unique_identifier_hash)
+
+                existing_document = await check_document_by_unique_identifier(
+                    session, unique_identifier_hash
+                )
+
+                if existing_document:
+                    # Check mtime first (cheap)
+                    stored_mtime = (existing_document.document_metadata or {}).get("mtime")
+                    current_mtime = file_info["modified_at"].timestamp()
+
+                    if stored_mtime and abs(current_mtime - stored_mtime) < 1.0:
+                        if not DocumentStatus.is_state(
+                            existing_document.status, DocumentStatus.READY
+                        ):
+                            existing_document.status = DocumentStatus.ready()
+                        skipped_count += 1
+                        continue
+
+                    # mtime differs — read file and check content hash
+                    try:
+                        content, content_hash = await _compute_file_content_hash(
+                            file_path_abs, file_info["relative_path"], search_space_id
+                        )
+                    except Exception as read_err:
+                        logger.warning(f"Could not read {file_path_abs}: {read_err}")
+                        skipped_count += 1
+                        continue
+
+                    if existing_document.content_hash == content_hash:
+                        # Content same, just update mtime in metadata
+                        meta = dict(existing_document.document_metadata or {})
+                        meta["mtime"] = current_mtime
+                        existing_document.document_metadata = meta
+                        if not DocumentStatus.is_state(
+                            existing_document.status, DocumentStatus.READY
+                        ):
+                            existing_document.status = DocumentStatus.ready()
+                        skipped_count += 1
+                        continue
+
+                    # Content actually changed — snapshot version, queue for re-index
+                    await create_version_snapshot(session, existing_document)
+
+                    files_to_process.append(
+                        {
+                            "document": existing_document,
+                            "is_new": False,
+                            "file_info": file_info,
+                            "content": content,
+                            "content_hash": content_hash,
+                            "unique_identifier_hash": unique_identifier_hash,
+                            "relative_path": relative_path,
+                            "title": file_info["name"],
+                        }
+                    )
+                    continue
+
+                # New document — read content
+                try:
+                    content, content_hash = await _compute_file_content_hash(
+                        file_path_abs, file_info["relative_path"], search_space_id
+                    )
+                except Exception as read_err:
+                    logger.warning(f"Could not read {file_path_abs}: {read_err}")
+                    skipped_count += 1
+                    continue
+
+                if not content.strip():
+                    skipped_count += 1
+                    continue
+
+                # Check for duplicate content from another connector
+                with session.no_autoflush:
+                    dup = await check_duplicate_document_by_hash(session, content_hash)
+                if dup:
+                    duplicate_count += 1
+                    skipped_count += 1
+                    continue
+
+                # Determine folder_id for this file
+                parent_dir = str(Path(relative_path).parent)
+                if parent_dir == ".":
+                    parent_dir = ""
+                folder_id = folder_mapping.get(parent_dir, folder_mapping.get(""))
+
+                document = Document(
+                    search_space_id=search_space_id,
+                    title=file_info["name"],
+                    document_type=DocumentType.LOCAL_FOLDER_FILE,
+                    document_metadata={
+                        "folder_name": folder_name,
+                        "file_path": relative_path,
+                        "connector_id": connector_id,
+                        "mtime": file_info["modified_at"].timestamp(),
+                    },
+                    content="Pending...",
+                    content_hash=unique_identifier_hash,  # Temp unique — updated in phase 2
+                    unique_identifier_hash=unique_identifier_hash,
+                    embedding=None,
+                    status=DocumentStatus.pending(),
+                    updated_at=get_current_timestamp(),
+                    created_by_id=user_id,
+                    connector_id=connector_id,
+                    folder_id=folder_id,
+                )
+                session.add(document)
+                new_documents_created = True
+
+                files_to_process.append(
+                    {
+                        "document": document,
+                        "is_new": True,
+                        "file_info": file_info,
+                        "content": content,
+                        "content_hash": content_hash,
+                        "unique_identifier_hash": unique_identifier_hash,
+                        "relative_path": relative_path,
+                        "title": file_info["name"],
+                    }
+                )
+
+            except Exception as e:
+                logger.exception(f"Phase 1 error for {file_info.get('path')}: {e}")
+                failed_count += 1
+
+        if new_documents_created:
+            await session.commit()
+
+        # ================================================================
+        # PHASE 1.5: Delete documents no longer on disk
+        # ================================================================
+        all_connector_docs = (
+            await session.execute(
+                select(Document).where(
+                    Document.connector_id == connector_id,
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                )
+            )
+        ).scalars().all()
+
+        for doc in all_connector_docs:
+            if doc.unique_identifier_hash not in seen_unique_hashes:
+                await session.delete(doc)
+
+        await session.flush()
+
+        # ================================================================
+        # PHASE 2: Process each document
+        # ================================================================
+        long_context_llm = await get_user_long_context_llm(
+            session, user_id, search_space_id
+        )
+
+        for item in files_to_process:
+            if on_heartbeat_callback:
+                current_time = time.time()
+                if current_time - last_heartbeat_time >= HEARTBEAT_INTERVAL_SECONDS:
+                    await on_heartbeat_callback(indexed_count)
+                    last_heartbeat_time = current_time
+
+            document = item["document"]
+            try:
+                document.status = DocumentStatus.processing()
+                await session.commit()
+
+                title = item["title"]
+                relative_path = item["relative_path"]
+                content = item["content"]
+                content_hash = item["content_hash"]
+                file_info = item["file_info"]
+
+                metadata_sections = [
+                    (
+                        "METADATA",
+                        [
+                            f"Title: {title}",
+                            f"Folder: {folder_name}",
+                            f"Path: {relative_path}",
+                        ],
+                    ),
+                    ("CONTENT", [content]),
+                ]
+                document_string = build_document_metadata_string(metadata_sections)
+
+                summary_content = ""
+                if long_context_llm and connector.enable_summary:
+                    doc_meta = {
+                        "folder_name": folder_name,
+                        "file_path": relative_path,
+                    }
+                    summary_content, _ = await generate_document_summary(
+                        document_string, long_context_llm, doc_meta
+                    )
+
+                embedding = embed_text(document_string)
+                chunks = await create_document_chunks(document_string)
+
+                # Determine folder_id
+                parent_dir = str(Path(relative_path).parent)
+                if parent_dir == ".":
+                    parent_dir = ""
+                folder_id = folder_mapping.get(parent_dir, folder_mapping.get(""))
+
+                document.title = title
+                document.content = document_string
+                document.content_hash = content_hash
+                document.source_markdown = content
+                document.embedding = embedding
+                document.document_metadata = {
+                    "folder_name": folder_name,
+                    "file_path": relative_path,
+                    "connector_id": connector_id,
+                    "summary": summary_content,
+                    "mtime": file_info["modified_at"].timestamp(),
+                }
+                document.folder_id = folder_id
+                await safe_set_chunks(session, document, chunks)
+                document.updated_at = get_current_timestamp()
+                document.status = DocumentStatus.ready()
+
+                indexed_count += 1
+
+                if indexed_count % 10 == 0:
+                    await session.commit()
+
+            except Exception as e:
+                logger.exception(f"Phase 2 error for {item.get('relative_path')}: {e}")
+                try:
+                    await session.rollback()
+                except Exception:
+                    pass
+                try:
+                    document.status = DocumentStatus.failed(str(e)[:500])
+                    document.updated_at = get_current_timestamp()
+                    await session.commit()
+                except Exception:
+                    try:
+                        await session.rollback()
+                    except Exception:
+                        pass
+                failed_count += 1
+
+        # Cleanup empty folders
+        existing_dirs = set()
+        for dirpath, dirnames, _ in os.walk(folder_path):
+            dirnames[:] = [d for d in dirnames if d not in exclude_patterns]
+            rel = str(Path(dirpath).relative_to(folder_path))
+            if rel == ".":
+                rel = ""
+            if rel and not any(part in exclude_patterns for part in Path(rel).parts):
+                existing_dirs.add(rel)
+
+        root_fid = folder_mapping.get("")
+        if root_fid:
+            await _cleanup_empty_folders(
+                session, root_fid, search_space_id, existing_dirs, folder_mapping
+            )
+
+        await update_connector_last_indexed(session, connector, update_last_indexed)
+
+        try:
+            await session.commit()
+        except Exception as e:
+            if "duplicate key value violates unique constraint" in str(e).lower():
+                logger.warning(f"Duplicate key during commit: {e}")
+                await session.rollback()
+            else:
+                raise
+
+        warning_parts = []
+        if duplicate_count > 0:
+            warning_parts.append(f"{duplicate_count} duplicate")
+        if failed_count > 0:
+            warning_parts.append(f"{failed_count} failed")
+        warning_message = ", ".join(warning_parts) if warning_parts else None
+
+        await task_logger.log_task_success(
+            log_entry,
+            f"Completed local folder indexing for connector {connector_id}",
+            {
+                "indexed": indexed_count,
+                "skipped": skipped_count,
+                "failed": failed_count,
+                "duplicates": duplicate_count,
+            },
+        )
+
+        return indexed_count, skipped_count, warning_message
+
+    except SQLAlchemyError as e:
+        logger.exception(f"Database error during local folder indexing: {e}")
+        await session.rollback()
+        await task_logger.log_task_failure(
+            log_entry, f"DB error: {e}", "Database error", {}
+        )
+        return 0, 0, f"Database error: {e}"
+
+    except Exception as e:
+        logger.exception(f"Error during local folder indexing: {e}")
+        await task_logger.log_task_failure(
+            log_entry, f"Error: {e}", "Unexpected error", {}
+        )
+        return 0, 0, str(e)
+
+
+async def _index_single_file(
+    session: AsyncSession,
+    connector,
+    connector_id: int,
+    search_space_id: int,
+    user_id: str,
+    folder_path: str,
+    folder_name: str,
+    target_file_path: str,
+    task_logger,
+    log_entry,
+    update_last_indexed: bool = True,
+) -> tuple[int, int, str | None]:
+    """Process a single file (chokidar real-time trigger)."""
+    try:
+        full_path = Path(target_file_path)
+        if not full_path.exists():
+            # File was deleted — find and remove the document
+            rel = str(full_path.relative_to(folder_path))
+            unique_id = f"{folder_name}:{rel}"
+            uid_hash = generate_unique_identifier_hash(
+                DocumentType.LOCAL_FOLDER_FILE, unique_id, search_space_id
+            )
+            existing = await check_document_by_unique_identifier(session, uid_hash)
+            if existing:
+                await session.delete(existing)
+                await session.commit()
+                return 0, 0, None
+            return 0, 0, None
+
+        rel_path = str(full_path.relative_to(folder_path))
+
+        unique_id = f"{folder_name}:{rel_path}"
+        uid_hash = generate_unique_identifier_hash(
+            DocumentType.LOCAL_FOLDER_FILE, unique_id, search_space_id
+        )
+
+        try:
+            content, content_hash = await _compute_file_content_hash(
+                str(full_path), full_path.name, search_space_id
+            )
+        except Exception as e:
+            return 0, 1, f"Could not read file: {e}"
+
+        if not content.strip():
+            return 0, 1, None
+
+        existing = await check_document_by_unique_identifier(session, uid_hash)
+
+        if existing:
+            if existing.content_hash == content_hash:
+                # Update mtime
+                mtime = full_path.stat().st_mtime
+                meta = dict(existing.document_metadata or {})
+                meta["mtime"] = mtime
+                existing.document_metadata = meta
+                await session.commit()
+                return 0, 1, None
+
+            # Content changed — snapshot + re-index
+            await create_version_snapshot(session, existing)
+
+        # Get LLM
+        long_context_llm = await get_user_long_context_llm(
+            session, user_id, search_space_id
+        )
+
+        title = full_path.name
+        mtime = full_path.stat().st_mtime
+
+        metadata_sections = [
+            ("METADATA", [f"Title: {title}", f"Folder: {folder_name}", f"Path: {rel_path}"]),
+            ("CONTENT", [content]),
+        ]
+        document_string = build_document_metadata_string(metadata_sections)
+
+        summary_content = ""
+        if long_context_llm and connector.enable_summary:
+            summary_content, _ = await generate_document_summary(
+                document_string, long_context_llm, {"folder_name": folder_name, "file_path": rel_path}
+            )
+
+        embedding = embed_text(document_string)
+        chunks = await create_document_chunks(document_string)
+
+        doc_metadata = {
+            "folder_name": folder_name,
+            "file_path": rel_path,
+            "connector_id": connector_id,
+            "summary": summary_content,
+            "mtime": mtime,
+        }
+
+        if existing:
+            existing.title = title
+            existing.content = document_string
+            existing.content_hash = content_hash
+            existing.source_markdown = content
+            existing.embedding = embedding
+            existing.document_metadata = doc_metadata
+            await safe_set_chunks(session, existing, chunks)
+            existing.updated_at = get_current_timestamp()
+            existing.status = DocumentStatus.ready()
+        else:
+            document = Document(
+                search_space_id=search_space_id,
+                title=title,
+                document_type=DocumentType.LOCAL_FOLDER_FILE,
+                document_metadata=doc_metadata,
+                content=document_string,
+                content_hash=content_hash,
+                unique_identifier_hash=uid_hash,
+                source_markdown=content,
+                embedding=embedding,
+                status=DocumentStatus.ready(),
+                updated_at=get_current_timestamp(),
+                created_by_id=user_id,
+                connector_id=connector_id,
+            )
+            session.add(document)
+            # Set chunks
+            await session.flush()
+            for chunk in chunks:
+                chunk.document_id = document.id
+            session.add_all(chunks)
+
+        await update_connector_last_indexed(session, connector, update_last_indexed)
+        await session.commit()
+
+        await task_logger.log_task_success(
+            log_entry,
+            f"Single file indexed: {rel_path}",
+            {"file": rel_path},
+        )
+        return 1, 0, None
+
+    except Exception as e:
+        logger.exception(f"Error indexing single file {target_file_path}: {e}")
+        await session.rollback()
+        return 0, 0, str(e)
diff --git a/surfsense_backend/app/utils/document_versioning.py b/surfsense_backend/app/utils/document_versioning.py
new file mode 100644
index 000000000..889bc4a3a
--- /dev/null
+++ b/surfsense_backend/app/utils/document_versioning.py
@@ -0,0 +1,107 @@
+"""Document versioning: snapshot creation and cleanup.
+
+Rules:
+- 30-minute debounce window: if the latest version was created < 30 min ago,
+  overwrite it instead of creating a new row.
+- Maximum 20 versions per document.
+- Versions older than 90 days are cleaned up.
+"""
+
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import delete, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db import Document, DocumentVersion
+
+MAX_VERSIONS_PER_DOCUMENT = 20
+DEBOUNCE_MINUTES = 30
+RETENTION_DAYS = 90
+
+
+def _now() -> datetime:
+    return datetime.now(UTC)
+
+
+async def create_version_snapshot(
+    session: AsyncSession,
+    document: Document,
+) -> DocumentVersion | None:
+    """Snapshot the document's current state into a DocumentVersion row.
+
+    Returns the created/updated DocumentVersion, or None if nothing was done.
+    """
+    now = _now()
+
+    latest = (
+        await session.execute(
+            select(DocumentVersion)
+            .where(DocumentVersion.document_id == document.id)
+            .order_by(DocumentVersion.version_number.desc())
+            .limit(1)
+        )
+    ).scalar_one_or_none()
+
+    if latest is not None:
+        age = now - latest.created_at.replace(tzinfo=UTC)
+        if age < timedelta(minutes=DEBOUNCE_MINUTES):
+            latest.source_markdown = document.source_markdown
+            latest.content_hash = document.content_hash
+            latest.title = document.title
+            latest.created_at = now
+            await session.flush()
+            return latest
+
+    max_num = (
+        await session.execute(
+            select(func.coalesce(func.max(DocumentVersion.version_number), 0)).where(
+                DocumentVersion.document_id == document.id
+            )
+        )
+    ).scalar_one()
+
+    version = DocumentVersion(
+        document_id=document.id,
+        version_number=max_num + 1,
+        source_markdown=document.source_markdown,
+        content_hash=document.content_hash,
+        title=document.title,
+        created_at=now,
+    )
+    session.add(version)
+    await session.flush()
+
+    # Cleanup: remove versions older than 90 days
+    cutoff = now - timedelta(days=RETENTION_DAYS)
+    await session.execute(
+        delete(DocumentVersion).where(
+            DocumentVersion.document_id == document.id,
+            DocumentVersion.created_at < cutoff,
+        )
+    )
+
+    # Cleanup: cap at MAX_VERSIONS_PER_DOCUMENT
+    count = (
+        await session.execute(
+            select(func.count()).select_from(DocumentVersion).where(
+                DocumentVersion.document_id == document.id
+            )
+        )
+    ).scalar_one()
+
+    if count > MAX_VERSIONS_PER_DOCUMENT:
+        excess = count - MAX_VERSIONS_PER_DOCUMENT
+        oldest_ids_result = await session.execute(
+            select(DocumentVersion.id)
+            .where(DocumentVersion.document_id == document.id)
+            .order_by(DocumentVersion.version_number.asc())
+            .limit(excess)
+        )
+        oldest_ids = [row[0] for row in oldest_ids_result.all()]
+        if oldest_ids:
+            await session.execute(
+                delete(DocumentVersion).where(DocumentVersion.id.in_(oldest_ids))
+            )
+
+    await session.flush()
+    return version

From 775dea7894f5737de3ab79bd5230b595f2dcc956 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 11:12:16 +0530
Subject: [PATCH 15/70] feat: add integration and unit tests for local folder
 indexing and document versioning

---
 .../tests/integration/conftest.py             |  21 +
 .../test_local_folder_pipeline.py             | 609 ++++++++++++++++++
 .../integration/test_document_versioning.py   | 184 ++++++
 .../test_local_folder_scan.py                 |  80 +++
 4 files changed, 894 insertions(+)
 create mode 100644 surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
 create mode 100644 surfsense_backend/tests/integration/test_document_versioning.py
 create mode 100644 surfsense_backend/tests/unit/connector_indexers/test_local_folder_scan.py

diff --git a/surfsense_backend/tests/integration/conftest.py b/surfsense_backend/tests/integration/conftest.py
index d9d7cacae..840246e2f 100644
--- a/surfsense_backend/tests/integration/conftest.py
+++ b/surfsense_backend/tests/integration/conftest.py
@@ -166,3 +166,24 @@ def make_connector_document(db_connector, db_user):
         return ConnectorDocument(**defaults)
 
     return _make
+
+
+@pytest_asyncio.fixture
+async def db_local_folder_connector(
+    db_session: AsyncSession, db_user: User, db_search_space: SearchSpace, tmp_path
+) -> SearchSourceConnector:
+    connector = SearchSourceConnector(
+        name="Test Local Folder",
+        connector_type=SearchSourceConnectorType.LOCAL_FOLDER_CONNECTOR,
+        config={
+            "folder_path": str(tmp_path),
+            "folder_name": "test-folder",
+            "exclude_patterns": [],
+            "file_extensions": None,
+        },
+        search_space_id=db_search_space.id,
+        user_id=db_user.id,
+    )
+    db_session.add(connector)
+    await db_session.flush()
+    return connector
diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
new file mode 100644
index 000000000..988905f8f
--- /dev/null
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -0,0 +1,609 @@
+"""Integration tests for local folder indexer — Tier 3 (I1-I5), Tier 4 (F1-F5), Tier 5 (P1)."""
+
+import os
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db import (
+    Document,
+    DocumentStatus,
+    DocumentType,
+    DocumentVersion,
+    Folder,
+    SearchSourceConnector,
+    SearchSpace,
+    User,
+)
+
+import app.tasks.connector_indexers.local_folder_indexer as _lfi_mod
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture
+def patched_self_hosted(monkeypatch):
+    _cfg = type("_Cfg", (), {"is_self_hosted": staticmethod(lambda: True)})()
+    monkeypatch.setattr(_lfi_mod, "config", _cfg)
+
+
+@pytest.fixture
+def patched_embed_for_indexer(monkeypatch):
+    from app.config import config as app_config
+    dim = app_config.embedding_model_instance.dimension
+    mock = MagicMock(return_value=[0.1] * dim)
+    monkeypatch.setattr(_lfi_mod, "embed_text", mock)
+    return mock
+
+
+@pytest.fixture
+def patched_chunks_for_indexer(monkeypatch):
+    from app.db import Chunk
+    from app.config import config as app_config
+    dim = app_config.embedding_model_instance.dimension
+
+    async def mock_create_chunks(text):
+        return [Chunk(content="chunk", embedding=[0.1] * dim)]
+
+    monkeypatch.setattr(_lfi_mod, "create_document_chunks", mock_create_chunks)
+
+
+@pytest.fixture
+def patched_summary_for_indexer(monkeypatch):
+    monkeypatch.setattr(_lfi_mod, "get_user_long_context_llm", AsyncMock(return_value=None))
+
+
+# ====================================================================
+# Tier 3: Full Indexer Integration (I1-I5)
+# ====================================================================
+
+
+class TestFullIndexer:
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_i1_new_file_indexed(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """I1: Single new .md file is indexed with status READY."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "note.md").write_text("# Hello World\n\nContent here.")
+
+        count, skipped, err = await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        assert err is None
+        assert count == 1
+
+        docs = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.connector_id == db_local_folder_connector.id
+                )
+            )
+        ).scalars().all()
+        assert len(docs) == 1
+        assert docs[0].document_type == DocumentType.LOCAL_FOLDER_FILE
+        assert DocumentStatus.is_state(docs[0].status, DocumentStatus.READY)
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_i2_unchanged_skipped(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """I2: Second run on unchanged directory creates no new documents."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "note.md").write_text("# Hello\n\nSame content.")
+
+        count1, _, _ = await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+        assert count1 == 1
+
+        # Second run — unchanged
+        count2, _, _ = await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+        assert count2 == 0
+
+        total = (
+            await db_session.execute(
+                select(func.count()).select_from(Document).where(
+                    Document.connector_id == db_local_folder_connector.id
+                )
+            )
+        ).scalar_one()
+        assert total == 1
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_i3_changed_reindexed(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """I3: Modified file content triggers re-index and creates a version."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        f = tmp_path / "note.md"
+        f.write_text("# Version 1\n\nOriginal.")
+
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        # Modify
+        f.write_text("# Version 2\n\nUpdated.")
+        # Touch mtime to ensure it's detected as different
+        os.utime(f, (f.stat().st_atime + 10, f.stat().st_mtime + 10))
+
+        count, _, _ = await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+        assert count == 1
+
+        # Should have a version snapshot
+        versions = (
+            await db_session.execute(
+                select(DocumentVersion).join(Document).where(
+                    Document.connector_id == db_local_folder_connector.id
+                )
+            )
+        ).scalars().all()
+        assert len(versions) >= 1
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_i4_deleted_removed(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """I4: Deleted file is removed from DB on re-sync."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        f = tmp_path / "to_delete.md"
+        f.write_text("# Delete me")
+
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        docs_before = (
+            await db_session.execute(
+                select(func.count()).select_from(Document).where(
+                    Document.connector_id == db_local_folder_connector.id
+                )
+            )
+        ).scalar_one()
+        assert docs_before == 1
+
+        f.unlink()
+
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        docs_after = (
+            await db_session.execute(
+                select(func.count()).select_from(Document).where(
+                    Document.connector_id == db_local_folder_connector.id
+                )
+            )
+        ).scalar_one()
+        assert docs_after == 0
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_i5_single_file_mode(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """I5: Single-file mode only processes the specified file."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "a.md").write_text("File A")
+        (tmp_path / "b.md").write_text("File B")
+        (tmp_path / "c.md").write_text("File C")
+
+        count, _, _ = await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            target_file_path=str(tmp_path / "b.md"),
+        )
+        assert count == 1
+
+        docs = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.connector_id == db_local_folder_connector.id
+                )
+            )
+        ).scalars().all()
+        assert len(docs) == 1
+        assert docs[0].title == "b"
+
+
+# ====================================================================
+# Tier 4: Folder Mirroring (F1-F5)
+# ====================================================================
+
+
+class TestFolderMirroring:
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_f1_root_folder_created(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """F1: First sync creates a root Folder and stores root_folder_id."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "root.md").write_text("Root file")
+
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        # Refresh connector
+        await db_session.refresh(db_local_folder_connector)
+        root_id = db_local_folder_connector.config.get("root_folder_id")
+        assert root_id is not None
+
+        root_folder = (
+            await db_session.execute(select(Folder).where(Folder.id == root_id))
+        ).scalar_one()
+        assert root_folder.name == "test-folder"
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_f2_nested_folder_rows(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """F2: Nested dirs create Folder rows with correct parent_id chain."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        daily = tmp_path / "notes" / "daily"
+        daily.mkdir(parents=True)
+        weekly = tmp_path / "notes" / "weekly"
+        weekly.mkdir(parents=True)
+        (daily / "today.md").write_text("today")
+        (weekly / "review.md").write_text("review")
+
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        folders = (
+            await db_session.execute(
+                select(Folder).where(Folder.search_space_id == db_search_space.id)
+            )
+        ).scalars().all()
+
+        folder_names = {f.name for f in folders}
+        assert "notes" in folder_names
+        assert "daily" in folder_names
+        assert "weekly" in folder_names
+
+        notes_folder = next(f for f in folders if f.name == "notes")
+        daily_folder = next(f for f in folders if f.name == "daily")
+        weekly_folder = next(f for f in folders if f.name == "weekly")
+
+        assert daily_folder.parent_id == notes_folder.id
+        assert weekly_folder.parent_id == notes_folder.id
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_f3_resync_reuses_folders(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """F3: Re-sync reuses existing Folder rows, no duplicates."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        sub = tmp_path / "docs"
+        sub.mkdir()
+        (sub / "file.md").write_text("content")
+
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        folders_before = (
+            await db_session.execute(
+                select(Folder).where(Folder.search_space_id == db_search_space.id)
+            )
+        ).scalars().all()
+        ids_before = {f.id for f in folders_before}
+
+        # Re-sync
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        folders_after = (
+            await db_session.execute(
+                select(Folder).where(Folder.search_space_id == db_search_space.id)
+            )
+        ).scalars().all()
+        ids_after = {f.id for f in folders_after}
+
+        assert ids_before == ids_after
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_f4_folder_id_assigned(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """F4: Documents get correct folder_id based on their directory."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        daily = tmp_path / "notes" / "daily"
+        daily.mkdir(parents=True)
+        (daily / "today.md").write_text("today note")
+        (tmp_path / "root.md").write_text("root note")
+
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        docs = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.connector_id == db_local_folder_connector.id
+                )
+            )
+        ).scalars().all()
+
+        today_doc = next(d for d in docs if d.title == "today")
+        root_doc = next(d for d in docs if d.title == "root")
+
+        daily_folder = (
+            await db_session.execute(
+                select(Folder).where(Folder.name == "daily")
+            )
+        ).scalar_one()
+
+        assert today_doc.folder_id == daily_folder.id
+
+        # Root doc should be in the root folder
+        await db_session.refresh(db_local_folder_connector)
+        root_fid = db_local_folder_connector.config.get("root_folder_id")
+        assert root_doc.folder_id == root_fid
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_f5_empty_folder_cleanup(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """F5: Deleted dir's empty Folder row is cleaned up on re-sync."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+        import shutil
+
+        daily = tmp_path / "notes" / "daily"
+        daily.mkdir(parents=True)
+        weekly = tmp_path / "notes" / "weekly"
+        weekly.mkdir(parents=True)
+        (daily / "today.md").write_text("today")
+        (weekly / "review.md").write_text("review")
+
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        # Verify weekly folder exists
+        weekly_folder = (
+            await db_session.execute(
+                select(Folder).where(Folder.name == "weekly")
+            )
+        ).scalar_one_or_none()
+        assert weekly_folder is not None
+
+        # Delete weekly directory + its file
+        shutil.rmtree(weekly)
+
+        await index_local_folder(
+            session=db_session,
+            connector_id=db_local_folder_connector.id,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+        )
+
+        # weekly Folder should be gone (empty, dir removed)
+        weekly_after = (
+            await db_session.execute(
+                select(Folder).where(Folder.name == "weekly")
+            )
+        ).scalar_one_or_none()
+        assert weekly_after is None
+
+        # daily should still exist
+        daily_after = (
+            await db_session.execute(
+                select(Folder).where(Folder.name == "daily")
+            )
+        ).scalar_one_or_none()
+        assert daily_after is not None
+
+
+# ====================================================================
+# Tier 5: Pipeline Integration (P1)
+# ====================================================================
+
+
+class TestPipelineIntegration:
+
+    @pytest.mark.usefixtures(
+        "patched_summarize", "patched_embed_texts", "patched_chunk_text"
+    )
+    async def test_p1_local_folder_file_through_pipeline(
+        self,
+        db_session: AsyncSession,
+        db_local_folder_connector: SearchSourceConnector,
+        db_user: User,
+        db_search_space: SearchSpace,
+        mocker,
+    ):
+        """P1: LOCAL_FOLDER_FILE ConnectorDocument through prepare+index to READY."""
+        from app.indexing_pipeline.connector_document import ConnectorDocument
+        from app.indexing_pipeline.indexing_pipeline_service import IndexingPipelineService
+
+        doc = ConnectorDocument(
+            title="Test Local File",
+            source_markdown="## Local file\n\nContent from disk.",
+            unique_id="test-folder:test.md",
+            document_type=DocumentType.LOCAL_FOLDER_FILE,
+            search_space_id=db_search_space.id,
+            connector_id=db_local_folder_connector.id,
+            created_by_id=str(db_user.id),
+        )
+
+        service = IndexingPipelineService(session=db_session)
+        prepared = await service.prepare_for_indexing([doc])
+        assert len(prepared) == 1
+
+        db_doc = prepared[0]
+        result = await service.index(db_doc, doc, llm=mocker.Mock())
+        assert result is not None
+
+        docs = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
+                )
+            )
+        ).scalars().all()
+        assert len(docs) == 1
+        assert DocumentStatus.is_state(docs[0].status, DocumentStatus.READY)
diff --git a/surfsense_backend/tests/integration/test_document_versioning.py b/surfsense_backend/tests/integration/test_document_versioning.py
new file mode 100644
index 000000000..87e3c490c
--- /dev/null
+++ b/surfsense_backend/tests/integration/test_document_versioning.py
@@ -0,0 +1,184 @@
+"""Integration tests for document versioning snapshot + cleanup."""
+
+from datetime import UTC, datetime, timedelta
+
+import pytest
+import pytest_asyncio
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.db import Document, DocumentType, DocumentVersion, SearchSpace, User
+
+pytestmark = pytest.mark.integration
+
+
+@pytest_asyncio.fixture
+async def db_document(
+    db_session: AsyncSession, db_user: User, db_search_space: SearchSpace
+) -> Document:
+    doc = Document(
+        title="Test Doc",
+        document_type=DocumentType.LOCAL_FOLDER_FILE,
+        document_metadata={},
+        content="Summary of test doc.",
+        content_hash="abc123",
+        unique_identifier_hash="local_folder:test-folder:test.md",
+        source_markdown="# Test\n\nOriginal content.",
+        search_space_id=db_search_space.id,
+        created_by_id=db_user.id,
+    )
+    db_session.add(doc)
+    await db_session.flush()
+    return doc
+
+
+async def _version_count(session: AsyncSession, document_id: int) -> int:
+    result = await session.execute(
+        select(func.count()).select_from(DocumentVersion).where(
+            DocumentVersion.document_id == document_id
+        )
+    )
+    return result.scalar_one()
+
+
+async def _get_versions(session: AsyncSession, document_id: int) -> list[DocumentVersion]:
+    result = await session.execute(
+        select(DocumentVersion)
+        .where(DocumentVersion.document_id == document_id)
+        .order_by(DocumentVersion.version_number)
+    )
+    return list(result.scalars().all())
+
+
+class TestCreateVersionSnapshot:
+    """V1-V5: TDD slices for create_version_snapshot."""
+
+    async def test_v1_creates_first_version(self, db_session, db_document):
+        """V1: First snapshot creates version 1 with the document's current state."""
+        from app.utils.document_versioning import create_version_snapshot
+
+        await create_version_snapshot(db_session, db_document)
+
+        versions = await _get_versions(db_session, db_document.id)
+        assert len(versions) == 1
+        assert versions[0].version_number == 1
+        assert versions[0].source_markdown == "# Test\n\nOriginal content."
+        assert versions[0].content_hash == "abc123"
+        assert versions[0].title == "Test Doc"
+        assert versions[0].document_id == db_document.id
+
+    async def test_v2_creates_version_2_after_30_min(
+        self, db_session, db_document, monkeypatch
+    ):
+        """V2: After 30+ minutes, a new version is created (not overwritten)."""
+        from app.utils.document_versioning import create_version_snapshot
+
+        t0 = datetime(2025, 1, 1, 12, 0, 0, tzinfo=UTC)
+        monkeypatch.setattr(
+            "app.utils.document_versioning._now", lambda: t0
+        )
+        await create_version_snapshot(db_session, db_document)
+
+        # Simulate content change and time passing
+        db_document.source_markdown = "# Test\n\nUpdated content."
+        db_document.content_hash = "def456"
+        t1 = t0 + timedelta(minutes=31)
+        monkeypatch.setattr(
+            "app.utils.document_versioning._now", lambda: t1
+        )
+        await create_version_snapshot(db_session, db_document)
+
+        versions = await _get_versions(db_session, db_document.id)
+        assert len(versions) == 2
+        assert versions[0].version_number == 1
+        assert versions[1].version_number == 2
+        assert versions[1].source_markdown == "# Test\n\nUpdated content."
+
+    async def test_v3_overwrites_within_30_min(
+        self, db_session, db_document, monkeypatch
+    ):
+        """V3: Within 30 minutes, the latest version is overwritten."""
+        from app.utils.document_versioning import create_version_snapshot
+
+        t0 = datetime(2025, 1, 1, 12, 0, 0, tzinfo=UTC)
+        monkeypatch.setattr(
+            "app.utils.document_versioning._now", lambda: t0
+        )
+        await create_version_snapshot(db_session, db_document)
+        count_after_first = await _version_count(db_session, db_document.id)
+        assert count_after_first == 1
+
+        # Simulate quick edit within 30 minutes
+        db_document.source_markdown = "# Test\n\nQuick edit."
+        db_document.content_hash = "quick123"
+        t1 = t0 + timedelta(minutes=10)
+        monkeypatch.setattr(
+            "app.utils.document_versioning._now", lambda: t1
+        )
+        await create_version_snapshot(db_session, db_document)
+
+        count_after_second = await _version_count(db_session, db_document.id)
+        assert count_after_second == 1  # still 1, not 2
+
+        versions = await _get_versions(db_session, db_document.id)
+        assert versions[0].source_markdown == "# Test\n\nQuick edit."
+        assert versions[0].content_hash == "quick123"
+
+    async def test_v4_cleanup_90_day_old_versions(
+        self, db_session, db_document, monkeypatch
+    ):
+        """V4: Versions older than 90 days are cleaned up."""
+        from app.utils.document_versioning import create_version_snapshot
+
+        base = datetime(2025, 1, 1, 12, 0, 0, tzinfo=UTC)
+
+        # Create 5 versions spread across time: 3 older than 90 days, 2 recent
+        for i in range(5):
+            db_document.source_markdown = f"Content v{i+1}"
+            db_document.content_hash = f"hash_{i+1}"
+            if i < 3:
+                t = base + timedelta(days=i)  # old
+            else:
+                t = base + timedelta(days=100 + i)  # recent
+            monkeypatch.setattr(
+                "app.utils.document_versioning._now", lambda _t=t: _t
+            )
+            await create_version_snapshot(db_session, db_document)
+
+        # Now trigger cleanup from a "current" time that makes the first 3 versions > 90 days old
+        now = base + timedelta(days=200)
+        monkeypatch.setattr(
+            "app.utils.document_versioning._now", lambda: now
+        )
+        db_document.source_markdown = "Content v6"
+        db_document.content_hash = "hash_6"
+        await create_version_snapshot(db_session, db_document)
+
+        versions = await _get_versions(db_session, db_document.id)
+        # The first 3 (old) should be cleaned up; versions 4, 5, 6 remain
+        for v in versions:
+            age = now - v.created_at.replace(tzinfo=UTC)
+            assert age <= timedelta(days=90), f"Version {v.version_number} is too old"
+
+    async def test_v5_cap_at_20_versions(
+        self, db_session, db_document, monkeypatch
+    ):
+        """V5: More than 20 versions triggers cap — oldest gets deleted."""
+        from app.utils.document_versioning import create_version_snapshot
+
+        base = datetime(2025, 6, 1, 12, 0, 0, tzinfo=UTC)
+
+        # Create 21 versions (all within 90 days, each 31 min apart)
+        for i in range(21):
+            db_document.source_markdown = f"Content v{i+1}"
+            db_document.content_hash = f"hash_{i+1}"
+            t = base + timedelta(minutes=31 * i)
+            monkeypatch.setattr(
+                "app.utils.document_versioning._now", lambda _t=t: _t
+            )
+            await create_version_snapshot(db_session, db_document)
+
+        versions = await _get_versions(db_session, db_document.id)
+        assert len(versions) == 20
+        # The lowest version_number should be 2 (version 1 was the oldest and got capped)
+        assert versions[0].version_number == 2
diff --git a/surfsense_backend/tests/unit/connector_indexers/test_local_folder_scan.py b/surfsense_backend/tests/unit/connector_indexers/test_local_folder_scan.py
new file mode 100644
index 000000000..9b4c73f25
--- /dev/null
+++ b/surfsense_backend/tests/unit/connector_indexers/test_local_folder_scan.py
@@ -0,0 +1,80 @@
+"""Unit tests for scan_folder() pure logic — Tier 2 TDD slices (S1-S4)."""
+
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.unit
+
+
+class TestScanFolder:
+    """S1-S4: scan_folder() with real tmp_path filesystem."""
+
+    def test_s1_single_md_file(self, tmp_path: Path):
+        """S1: scan_folder on a dir with one .md file returns correct entry."""
+        from app.tasks.connector_indexers.local_folder_indexer import scan_folder
+
+        md = tmp_path / "note.md"
+        md.write_text("# Hello")
+
+        results = scan_folder(str(tmp_path))
+
+        assert len(results) == 1
+        entry = results[0]
+        assert entry["relative_path"] == "note.md"
+        assert entry["size"] > 0
+        assert "modified_at" in entry
+        assert entry["path"] == str(md)
+
+    def test_s2_extension_filter(self, tmp_path: Path):
+        """S2: file_extensions filter returns only matching files."""
+        from app.tasks.connector_indexers.local_folder_indexer import scan_folder
+
+        (tmp_path / "a.md").write_text("md")
+        (tmp_path / "b.txt").write_text("txt")
+        (tmp_path / "c.pdf").write_bytes(b"%PDF")
+
+        results = scan_folder(str(tmp_path), file_extensions=[".md"])
+        names = {r["relative_path"] for r in results}
+
+        assert names == {"a.md"}
+
+    def test_s3_exclude_patterns(self, tmp_path: Path):
+        """S3: exclude_patterns skips files inside excluded directories."""
+        from app.tasks.connector_indexers.local_folder_indexer import scan_folder
+
+        (tmp_path / "good.md").write_text("good")
+        nm = tmp_path / "node_modules"
+        nm.mkdir()
+        (nm / "dep.js").write_text("module")
+        git = tmp_path / ".git"
+        git.mkdir()
+        (git / "config").write_text("gitconfig")
+
+        results = scan_folder(
+            str(tmp_path), exclude_patterns=["node_modules", ".git"]
+        )
+        names = {r["relative_path"] for r in results}
+
+        assert "good.md" in names
+        assert not any("node_modules" in n for n in names)
+        assert not any(".git" in n for n in names)
+
+    def test_s4_nested_dirs(self, tmp_path: Path):
+        """S4: nested subdirectories produce correct relative paths."""
+        from app.tasks.connector_indexers.local_folder_indexer import scan_folder
+
+        daily = tmp_path / "notes" / "daily"
+        daily.mkdir(parents=True)
+        weekly = tmp_path / "notes" / "weekly"
+        weekly.mkdir(parents=True)
+        (daily / "today.md").write_text("today")
+        (weekly / "review.md").write_text("review")
+        (tmp_path / "root.txt").write_text("root")
+
+        results = scan_folder(str(tmp_path))
+        paths = {r["relative_path"] for r in results}
+
+        assert "notes/daily/today.md" in paths or "notes\\daily\\today.md" in paths
+        assert "notes/weekly/review.md" in paths or "notes\\weekly\\review.md" in paths
+        assert "root.txt" in paths

From 28f556224af78b618992cc40241e4834f5cc528c Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 11:17:49 +0530
Subject: [PATCH 16/70] feat: implement folder watching functionality with IPC
 integration

---
 surfsense_desktop/src/ipc/channels.ts         |  10 +
 surfsense_desktop/src/ipc/handlers.ts         |  28 +++
 surfsense_desktop/src/main.ts                 |   3 +
 .../src/modules/folder-watcher.ts             | 216 ++++++++++++++++++
 surfsense_desktop/src/preload.ts              |  23 ++
 5 files changed, 280 insertions(+)
 create mode 100644 surfsense_desktop/src/modules/folder-watcher.ts

diff --git a/surfsense_desktop/src/ipc/channels.ts b/surfsense_desktop/src/ipc/channels.ts
index 25ec1bc0e..362d3362d 100644
--- a/surfsense_desktop/src/ipc/channels.ts
+++ b/surfsense_desktop/src/ipc/channels.ts
@@ -6,4 +6,14 @@ export const IPC_CHANNELS = {
   SET_QUICK_ASK_MODE: 'set-quick-ask-mode',
   GET_QUICK_ASK_MODE: 'get-quick-ask-mode',
   REPLACE_TEXT: 'replace-text',
+  // Folder sync channels
+  FOLDER_SYNC_SELECT_FOLDER: 'folder-sync:select-folder',
+  FOLDER_SYNC_ADD_FOLDER: 'folder-sync:add-folder',
+  FOLDER_SYNC_REMOVE_FOLDER: 'folder-sync:remove-folder',
+  FOLDER_SYNC_GET_FOLDERS: 'folder-sync:get-folders',
+  FOLDER_SYNC_GET_STATUS: 'folder-sync:get-status',
+  FOLDER_SYNC_FILE_CHANGED: 'folder-sync:file-changed',
+  FOLDER_SYNC_WATCHER_READY: 'folder-sync:watcher-ready',
+  FOLDER_SYNC_PAUSE: 'folder-sync:pause',
+  FOLDER_SYNC_RESUME: 'folder-sync:resume',
 } as const;
diff --git a/surfsense_desktop/src/ipc/handlers.ts b/surfsense_desktop/src/ipc/handlers.ts
index 18e343719..2baf957b0 100644
--- a/surfsense_desktop/src/ipc/handlers.ts
+++ b/surfsense_desktop/src/ipc/handlers.ts
@@ -1,5 +1,14 @@
 import { app, ipcMain, shell } from 'electron';
 import { IPC_CHANNELS } from './channels';
+import {
+  selectFolder,
+  addWatchedFolder,
+  removeWatchedFolder,
+  getWatchedFolders,
+  getWatcherStatus,
+  pauseWatcher,
+  resumeWatcher,
+} from '../modules/folder-watcher';
 
 export function registerIpcHandlers(): void {
   ipcMain.on(IPC_CHANNELS.OPEN_EXTERNAL, (_event, url: string) => {
@@ -16,4 +25,23 @@ export function registerIpcHandlers(): void {
   ipcMain.handle(IPC_CHANNELS.GET_APP_VERSION, () => {
     return app.getVersion();
   });
+
+  // Folder sync handlers
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_SELECT_FOLDER, () => selectFolder());
+
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_ADD_FOLDER, (_event, config) =>
+    addWatchedFolder(config)
+  );
+
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_REMOVE_FOLDER, (_event, folderPath: string) =>
+    removeWatchedFolder(folderPath)
+  );
+
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_GET_FOLDERS, () => getWatchedFolders());
+
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_GET_STATUS, () => getWatcherStatus());
+
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_PAUSE, () => pauseWatcher());
+
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_RESUME, () => resumeWatcher());
 }
diff --git a/surfsense_desktop/src/main.ts b/surfsense_desktop/src/main.ts
index 3ab41073b..f745d9b5e 100644
--- a/surfsense_desktop/src/main.ts
+++ b/surfsense_desktop/src/main.ts
@@ -6,6 +6,7 @@ import { setupDeepLinks, handlePendingDeepLink } from './modules/deep-links';
 import { setupAutoUpdater } from './modules/auto-updater';
 import { setupMenu } from './modules/menu';
 import { registerQuickAsk, unregisterQuickAsk } from './modules/quick-ask';
+import { registerFolderWatcher, unregisterFolderWatcher } from './modules/folder-watcher';
 import { registerIpcHandlers } from './ipc/handlers';
 
 registerGlobalErrorHandlers();
@@ -28,6 +29,7 @@ app.whenReady().then(async () => {
   }
   createMainWindow();
   registerQuickAsk();
+  registerFolderWatcher();
   setupAutoUpdater();
 
   handlePendingDeepLink();
@@ -47,4 +49,5 @@ app.on('window-all-closed', () => {
 
 app.on('will-quit', () => {
   unregisterQuickAsk();
+  unregisterFolderWatcher();
 });
diff --git a/surfsense_desktop/src/modules/folder-watcher.ts b/surfsense_desktop/src/modules/folder-watcher.ts
new file mode 100644
index 000000000..bfd2136c9
--- /dev/null
+++ b/surfsense_desktop/src/modules/folder-watcher.ts
@@ -0,0 +1,216 @@
+import { BrowserWindow, dialog } from 'electron';
+import chokidar from 'chokidar';
+import * as path from 'path';
+import * as fs from 'fs';
+import { IPC_CHANNELS } from '../ipc/channels';
+
+export interface WatchedFolderConfig {
+  path: string;
+  name: string;
+  excludePatterns: string[];
+  fileExtensions: string[] | null;
+  connectorId: number;
+  searchSpaceId: number;
+  active: boolean;
+}
+
+interface WatcherEntry {
+  config: WatchedFolderConfig;
+  watcher: chokidar.FSWatcher | null;
+}
+
+const STORE_KEY = 'watchedFolders';
+let store: any = null;
+let watchers: Map<string, WatcherEntry> = new Map();
+
+async function getStore() {
+  if (!store) {
+    const { default: Store } = await import('electron-store');
+    store = new Store({
+      name: 'folder-watcher',
+      defaults: {
+        [STORE_KEY]: [] as WatchedFolderConfig[],
+      },
+    });
+  }
+  return store;
+}
+
+function getMainWindow(): BrowserWindow | null {
+  const windows = BrowserWindow.getAllWindows();
+  return windows.length > 0 ? windows[0] : null;
+}
+
+function sendToRenderer(channel: string, data: any) {
+  const win = getMainWindow();
+  if (win && !win.isDestroyed()) {
+    win.webContents.send(channel, data);
+  }
+}
+
+function startWatcher(config: WatchedFolderConfig) {
+  if (watchers.has(config.path)) {
+    return;
+  }
+
+  const ignored = [
+    /(^|[/\\])\../, // dotfiles by default
+    ...config.excludePatterns.map((p) => `**/${p}/**`),
+  ];
+
+  const watcher = chokidar.watch(config.path, {
+    persistent: true,
+    ignoreInitial: false,
+    awaitWriteFinish: {
+      stabilityThreshold: 500,
+      pollInterval: 100,
+    },
+    ignored,
+  });
+
+  let ready = false;
+
+  watcher.on('ready', () => {
+    ready = true;
+    sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_WATCHER_READY, {
+      connectorId: config.connectorId,
+      folderPath: config.path,
+    });
+  });
+
+  const handleFileEvent = (filePath: string, action: string) => {
+    if (!ready) return;
+
+    const relativePath = path.relative(config.path, filePath);
+
+    if (
+      config.fileExtensions &&
+      config.fileExtensions.length > 0
+    ) {
+      const ext = path.extname(filePath).toLowerCase();
+      if (!config.fileExtensions.includes(ext)) return;
+    }
+
+    sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, {
+      connectorId: config.connectorId,
+      searchSpaceId: config.searchSpaceId,
+      folderPath: config.path,
+      relativePath,
+      fullPath: filePath,
+      action,
+      timestamp: Date.now(),
+    });
+  };
+
+  watcher.on('add', (fp) => handleFileEvent(fp, 'add'));
+  watcher.on('change', (fp) => handleFileEvent(fp, 'change'));
+  watcher.on('unlink', (fp) => handleFileEvent(fp, 'unlink'));
+
+  watchers.set(config.path, { config, watcher });
+}
+
+function stopWatcher(folderPath: string) {
+  const entry = watchers.get(folderPath);
+  if (entry?.watcher) {
+    entry.watcher.close();
+  }
+  watchers.delete(folderPath);
+}
+
+export async function selectFolder(): Promise<string | null> {
+  const result = await dialog.showOpenDialog({
+    properties: ['openDirectory'],
+    title: 'Select a folder to watch',
+  });
+  if (result.canceled || result.filePaths.length === 0) {
+    return null;
+  }
+  return result.filePaths[0];
+}
+
+export async function addWatchedFolder(
+  config: WatchedFolderConfig
+): Promise<WatchedFolderConfig[]> {
+  const s = await getStore();
+  const folders: WatchedFolderConfig[] = s.get(STORE_KEY, []);
+
+  const existing = folders.findIndex((f: WatchedFolderConfig) => f.path === config.path);
+  if (existing >= 0) {
+    folders[existing] = config;
+  } else {
+    folders.push(config);
+  }
+
+  s.set(STORE_KEY, folders);
+
+  if (config.active) {
+    startWatcher(config);
+  }
+
+  return folders;
+}
+
+export async function removeWatchedFolder(
+  folderPath: string
+): Promise<WatchedFolderConfig[]> {
+  const s = await getStore();
+  const folders: WatchedFolderConfig[] = s.get(STORE_KEY, []);
+  const updated = folders.filter((f: WatchedFolderConfig) => f.path !== folderPath);
+  s.set(STORE_KEY, updated);
+
+  stopWatcher(folderPath);
+
+  return updated;
+}
+
+export async function getWatchedFolders(): Promise<WatchedFolderConfig[]> {
+  const s = await getStore();
+  return s.get(STORE_KEY, []);
+}
+
+export async function getWatcherStatus(): Promise<
+  { path: string; active: boolean; watching: boolean }[]
+> {
+  const s = await getStore();
+  const folders: WatchedFolderConfig[] = s.get(STORE_KEY, []);
+  return folders.map((f: WatchedFolderConfig) => ({
+    path: f.path,
+    active: f.active,
+    watching: watchers.has(f.path),
+  }));
+}
+
+export async function pauseWatcher(): Promise<void> {
+  for (const [, entry] of watchers) {
+    if (entry.watcher) {
+      await entry.watcher.close();
+      entry.watcher = null;
+    }
+  }
+}
+
+export async function resumeWatcher(): Promise<void> {
+  for (const [folderPath, entry] of watchers) {
+    if (!entry.watcher && entry.config.active) {
+      startWatcher(entry.config);
+    }
+  }
+}
+
+export async function registerFolderWatcher(): Promise<void> {
+  const s = await getStore();
+  const folders: WatchedFolderConfig[] = s.get(STORE_KEY, []);
+
+  for (const config of folders) {
+    if (config.active && fs.existsSync(config.path)) {
+      startWatcher(config);
+    }
+  }
+}
+
+export async function unregisterFolderWatcher(): Promise<void> {
+  for (const [folderPath] of watchers) {
+    stopWatcher(folderPath);
+  }
+  watchers.clear();
+}
diff --git a/surfsense_desktop/src/preload.ts b/surfsense_desktop/src/preload.ts
index 264ec25b3..8f65aa633 100644
--- a/surfsense_desktop/src/preload.ts
+++ b/surfsense_desktop/src/preload.ts
@@ -21,4 +21,27 @@ contextBridge.exposeInMainWorld('electronAPI', {
   setQuickAskMode: (mode: string) => ipcRenderer.invoke(IPC_CHANNELS.SET_QUICK_ASK_MODE, mode),
   getQuickAskMode: () => ipcRenderer.invoke(IPC_CHANNELS.GET_QUICK_ASK_MODE),
   replaceText: (text: string) => ipcRenderer.invoke(IPC_CHANNELS.REPLACE_TEXT, text),
+
+  // Folder sync
+  selectFolder: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_SELECT_FOLDER),
+  addWatchedFolder: (config: any) => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_ADD_FOLDER, config),
+  removeWatchedFolder: (folderPath: string) => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_REMOVE_FOLDER, folderPath),
+  getWatchedFolders: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_GET_FOLDERS),
+  getWatcherStatus: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_GET_STATUS),
+  onFileChanged: (callback: (data: any) => void) => {
+    const listener = (_event: unknown, data: any) => callback(data);
+    ipcRenderer.on(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, listener);
+    return () => {
+      ipcRenderer.removeListener(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, listener);
+    };
+  },
+  onWatcherReady: (callback: (data: any) => void) => {
+    const listener = (_event: unknown, data: any) => callback(data);
+    ipcRenderer.on(IPC_CHANNELS.FOLDER_SYNC_WATCHER_READY, listener);
+    return () => {
+      ipcRenderer.removeListener(IPC_CHANNELS.FOLDER_SYNC_WATCHER_READY, listener);
+    };
+  },
+  pauseWatcher: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_PAUSE),
+  resumeWatcher: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_RESUME),
 });

From e2f946b7c03c71496515ec722254d53de2155146 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 11:38:40 +0530
Subject: [PATCH 17/70] feat: add support for Local Folder connector in UI
 components and configuration

---
 .../[search_space_id]/client-layout.tsx       |  4 ++
 .../views/connector-connect-view.tsx          |  1 +
 .../views/connector-edit-view.tsx             | 69 ++++++++++---------
 .../views/indexing-configuration-view.tsx     | 12 ++--
 .../constants/connector-constants.ts          |  8 +++
 .../tabs/all-connectors-tab.tsx               | 25 +++----
 surfsense_web/contracts/enums/connector.ts    |  1 +
 .../contracts/enums/connectorIcons.tsx        |  3 +
 .../contracts/types/connector.types.ts        |  1 +
 9 files changed, 72 insertions(+), 52 deletions(-)

diff --git a/surfsense_web/app/dashboard/[search_space_id]/client-layout.tsx b/surfsense_web/app/dashboard/[search_space_id]/client-layout.tsx
index 1715e525f..60b8aef12 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/client-layout.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/client-layout.tsx
@@ -17,6 +17,7 @@ import { DocumentUploadDialogProvider } from "@/components/assistant-ui/document
 import { LayoutDataProvider } from "@/components/layout";
 import { OnboardingTour } from "@/components/onboarding-tour";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { useFolderSync } from "@/hooks/use-folder-sync";
 import { useGlobalLoadingEffect } from "@/hooks/use-global-loading";
 
 export function DashboardClientLayout({
@@ -159,6 +160,9 @@ export function DashboardClientLayout({
 	// Use global loading screen - spinner animation won't reset
 	useGlobalLoadingEffect(shouldShowLoading);
 
+	// Wire desktop app file watcher -> single-file re-index API
+	useFolderSync();
+
 	if (shouldShowLoading) {
 		return null;
 	}
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-connect-view.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-connect-view.tsx
index 596b98e93..0b6d0917a 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-connect-view.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-connect-view.tsx
@@ -20,6 +20,7 @@ const FORM_ID_MAP: Record<string, string> = {
 	CIRCLEBACK_CONNECTOR: "circleback-connect-form",
 	MCP_CONNECTOR: "mcp-connect-form",
 	OBSIDIAN_CONNECTOR: "obsidian-connect-form",
+	LOCAL_FOLDER_CONNECTOR: "local-folder-connect-form",
 };
 
 interface ConnectorConnectViewProps {
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx
index 20d4a8e53..dcedb4743 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx
@@ -272,13 +272,14 @@ export const ConnectorEditView: FC<ConnectorEditViewProps> = ({
 								{/* AI Summary toggle */}
 								<SummaryConfig enabled={enableSummary} onEnabledChange={onEnableSummaryChange} />
 
-								{/* Date range selector - not shown for file-based connectors (Drive, Dropbox, OneDrive), Webcrawler, or GitHub (indexes full repo snapshots) */}
+								{/* Date range selector - not shown for file-based connectors (Drive, Dropbox, OneDrive), Webcrawler, GitHub, or Local Folder */}
 								{connector.connector_type !== "GOOGLE_DRIVE_CONNECTOR" &&
 									connector.connector_type !== "COMPOSIO_GOOGLE_DRIVE_CONNECTOR" &&
 									connector.connector_type !== "DROPBOX_CONNECTOR" &&
 									connector.connector_type !== "ONEDRIVE_CONNECTOR" &&
 									connector.connector_type !== "WEBCRAWLER_CONNECTOR" &&
-									connector.connector_type !== "GITHUB_CONNECTOR" && (
+									connector.connector_type !== "GITHUB_CONNECTOR" &&
+									connector.connector_type !== "LOCAL_FOLDER_CONNECTOR" && (
 										<DateRangeSelector
 											startDate={startDate}
 											endDate={endDate}
@@ -293,39 +294,39 @@ export const ConnectorEditView: FC<ConnectorEditViewProps> = ({
 										/>
 									)}
 
-								{/* Periodic sync - shown for all indexable connectors */}
-								{(() => {
-									// Check if Google Drive (regular or Composio) has folders/files selected
-									const isGoogleDrive = connector.connector_type === "GOOGLE_DRIVE_CONNECTOR";
-									const isComposioGoogleDrive =
-										connector.connector_type === "COMPOSIO_GOOGLE_DRIVE_CONNECTOR";
-									const requiresFolderSelection = isGoogleDrive || isComposioGoogleDrive;
-									const selectedFolders =
-										(connector.config?.selected_folders as
-											| Array<{ id: string; name: string }>
-											| undefined) || [];
-									const selectedFiles =
-										(connector.config?.selected_files as
-											| Array<{ id: string; name: string }>
-											| undefined) || [];
-									const hasItemsSelected = selectedFolders.length > 0 || selectedFiles.length > 0;
-									const isDisabled = requiresFolderSelection && !hasItemsSelected;
+								{/* Periodic sync - shown for all indexable connectors except Local Folder */}
+								{connector.connector_type !== "LOCAL_FOLDER_CONNECTOR" &&
+									(() => {
+										const isGoogleDrive = connector.connector_type === "GOOGLE_DRIVE_CONNECTOR";
+										const isComposioGoogleDrive =
+											connector.connector_type === "COMPOSIO_GOOGLE_DRIVE_CONNECTOR";
+										const requiresFolderSelection = isGoogleDrive || isComposioGoogleDrive;
+										const selectedFolders =
+											(connector.config?.selected_folders as
+												| Array<{ id: string; name: string }>
+												| undefined) || [];
+										const selectedFiles =
+											(connector.config?.selected_files as
+												| Array<{ id: string; name: string }>
+												| undefined) || [];
+										const hasItemsSelected = selectedFolders.length > 0 || selectedFiles.length > 0;
+										const isDisabled = requiresFolderSelection && !hasItemsSelected;
 
-									return (
-										<PeriodicSyncConfig
-											enabled={periodicEnabled}
-											frequencyMinutes={frequencyMinutes}
-											onEnabledChange={onPeriodicEnabledChange}
-											onFrequencyChange={onFrequencyChange}
-											disabled={isDisabled}
-											disabledMessage={
-												isDisabled
-													? "Select at least one folder or file above to enable periodic sync"
-													: undefined
-											}
-										/>
-									);
-								})()}
+										return (
+											<PeriodicSyncConfig
+												enabled={periodicEnabled}
+												frequencyMinutes={frequencyMinutes}
+												onEnabledChange={onPeriodicEnabledChange}
+												onFrequencyChange={onFrequencyChange}
+												disabled={isDisabled}
+												disabledMessage={
+													isDisabled
+														? "Select at least one folder or file above to enable periodic sync"
+														: undefined
+												}
+											/>
+										);
+									})()}
 							</>
 						)}
 
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/indexing-configuration-view.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/indexing-configuration-view.tsx
index 564cb87ee..436ce7843 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/indexing-configuration-view.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/indexing-configuration-view.tsx
@@ -158,13 +158,14 @@ export const IndexingConfigurationView: FC<IndexingConfigurationViewProps> = ({
 								{/* AI Summary toggle */}
 								<SummaryConfig enabled={enableSummary} onEnabledChange={onEnableSummaryChange} />
 
-								{/* Date range selector - not shown for file-based connectors (Drive, Dropbox, OneDrive), Webcrawler, or GitHub (indexes full repo snapshots) */}
+								{/* Date range selector - not shown for file-based connectors (Drive, Dropbox, OneDrive), Webcrawler, GitHub, or Local Folder */}
 								{config.connectorType !== "GOOGLE_DRIVE_CONNECTOR" &&
 									config.connectorType !== "COMPOSIO_GOOGLE_DRIVE_CONNECTOR" &&
 									config.connectorType !== "DROPBOX_CONNECTOR" &&
 									config.connectorType !== "ONEDRIVE_CONNECTOR" &&
 									config.connectorType !== "WEBCRAWLER_CONNECTOR" &&
-									config.connectorType !== "GITHUB_CONNECTOR" && (
+									config.connectorType !== "GITHUB_CONNECTOR" &&
+									config.connectorType !== "LOCAL_FOLDER_CONNECTOR" && (
 										<DateRangeSelector
 											startDate={startDate}
 											endDate={endDate}
@@ -179,9 +180,12 @@ export const IndexingConfigurationView: FC<IndexingConfigurationViewProps> = ({
 										/>
 									)}
 
-								{/* Periodic sync - not shown for Google Drive (regular and Composio) */}
+								{/* Periodic sync - not shown for file-based connectors (Drive, Dropbox, OneDrive) or Local Folder in initial setup; configured in edit view instead */}
 								{config.connectorType !== "GOOGLE_DRIVE_CONNECTOR" &&
-									config.connectorType !== "COMPOSIO_GOOGLE_DRIVE_CONNECTOR" && (
+									config.connectorType !== "COMPOSIO_GOOGLE_DRIVE_CONNECTOR" &&
+									config.connectorType !== "DROPBOX_CONNECTOR" &&
+									config.connectorType !== "ONEDRIVE_CONNECTOR" &&
+									config.connectorType !== "LOCAL_FOLDER_CONNECTOR" && (
 										<PeriodicSyncConfig
 											enabled={periodicEnabled}
 											frequencyMinutes={frequencyMinutes}
diff --git a/surfsense_web/components/assistant-ui/connector-popup/constants/connector-constants.ts b/surfsense_web/components/assistant-ui/connector-popup/constants/connector-constants.ts
index 2e92f637b..3f7d90cd8 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/constants/connector-constants.ts
+++ b/surfsense_web/components/assistant-ui/connector-popup/constants/connector-constants.ts
@@ -184,6 +184,14 @@ export const OTHER_CONNECTORS = [
 		connectorType: EnumConnectorName.OBSIDIAN_CONNECTOR,
 		selfHostedOnly: true,
 	},
+	{
+		id: "local-folder-connector",
+		title: "Local Folder",
+		description: "Watch and sync local folders (desktop only)",
+		connectorType: EnumConnectorName.LOCAL_FOLDER_CONNECTOR,
+		selfHostedOnly: true,
+		desktopOnly: true,
+	},
 ] as const;
 
 // Composio Connectors - Individual entries for each supported toolkit
diff --git a/surfsense_web/components/assistant-ui/connector-popup/tabs/all-connectors-tab.tsx b/surfsense_web/components/assistant-ui/connector-popup/tabs/all-connectors-tab.tsx
index ad2418865..3e8aad620 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/tabs/all-connectors-tab.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/tabs/all-connectors-tab.tsx
@@ -76,29 +76,26 @@ export const AllConnectorsTab: FC<AllConnectorsTabProps> = ({
 }) => {
 	// Check if self-hosted mode (for showing self-hosted only connectors)
 	const selfHosted = isSelfHosted();
+	const isDesktop = typeof window !== "undefined" && !!window.electronAPI;
+
+	const matchesSearch = (title: string, description: string) =>
+		title.toLowerCase().includes(searchQuery.toLowerCase()) ||
+		description.toLowerCase().includes(searchQuery.toLowerCase());
+
+	const passesDeploymentFilter = (c: { selfHostedOnly?: boolean; desktopOnly?: boolean }) =>
+		(!c.selfHostedOnly || selfHosted) && (!c.desktopOnly || isDesktop);
 
 	// Filter connectors based on search and deployment mode
 	const filteredOAuth = OAUTH_CONNECTORS.filter(
-		(c) =>
-			// Filter by search query
-			(c.title.toLowerCase().includes(searchQuery.toLowerCase()) ||
-				c.description.toLowerCase().includes(searchQuery.toLowerCase())) &&
-			// Filter self-hosted only connectors in cloud mode
-			(!("selfHostedOnly" in c) || !c.selfHostedOnly || selfHosted)
+		(c) => matchesSearch(c.title, c.description) && passesDeploymentFilter(c)
 	);
 
 	const filteredCrawlers = CRAWLERS.filter(
-		(c) =>
-			(c.title.toLowerCase().includes(searchQuery.toLowerCase()) ||
-				c.description.toLowerCase().includes(searchQuery.toLowerCase())) &&
-			(!("selfHostedOnly" in c) || !c.selfHostedOnly || selfHosted)
+		(c) => matchesSearch(c.title, c.description) && passesDeploymentFilter(c)
 	);
 
 	const filteredOther = OTHER_CONNECTORS.filter(
-		(c) =>
-			(c.title.toLowerCase().includes(searchQuery.toLowerCase()) ||
-				c.description.toLowerCase().includes(searchQuery.toLowerCase())) &&
-			(!("selfHostedOnly" in c) || !c.selfHostedOnly || selfHosted)
+		(c) => matchesSearch(c.title, c.description) && passesDeploymentFilter(c)
 	);
 
 	// Filter Composio connectors
diff --git a/surfsense_web/contracts/enums/connector.ts b/surfsense_web/contracts/enums/connector.ts
index 501f5d9a3..ecf96d88e 100644
--- a/surfsense_web/contracts/enums/connector.ts
+++ b/surfsense_web/contracts/enums/connector.ts
@@ -25,6 +25,7 @@ export enum EnumConnectorName {
 	YOUTUBE_CONNECTOR = "YOUTUBE_CONNECTOR",
 	CIRCLEBACK_CONNECTOR = "CIRCLEBACK_CONNECTOR",
 	OBSIDIAN_CONNECTOR = "OBSIDIAN_CONNECTOR",
+	LOCAL_FOLDER_CONNECTOR = "LOCAL_FOLDER_CONNECTOR",
 	DROPBOX_CONNECTOR = "DROPBOX_CONNECTOR",
 	MCP_CONNECTOR = "MCP_CONNECTOR",
 	COMPOSIO_GOOGLE_DRIVE_CONNECTOR = "COMPOSIO_GOOGLE_DRIVE_CONNECTOR",
diff --git a/surfsense_web/contracts/enums/connectorIcons.tsx b/surfsense_web/contracts/enums/connectorIcons.tsx
index 2e609b060..f7378b74b 100644
--- a/surfsense_web/contracts/enums/connectorIcons.tsx
+++ b/surfsense_web/contracts/enums/connectorIcons.tsx
@@ -3,6 +3,7 @@ import {
 	BookOpen,
 	File,
 	FileText,
+	FolderSync,
 	Globe,
 	Microscope,
 	Search,
@@ -75,6 +76,8 @@ export const getConnectorIcon = (connectorType: EnumConnectorName | string, clas
 			return <Image src="/connectors/circleback.svg" alt="Circleback" {...imgProps} />;
 		case EnumConnectorName.MCP_CONNECTOR:
 			return <Image src="/connectors/modelcontextprotocol.svg" alt="MCP" {...imgProps} />;
+		case EnumConnectorName.LOCAL_FOLDER_CONNECTOR:
+			return <FolderSync {...iconProps} />;
 		case EnumConnectorName.OBSIDIAN_CONNECTOR:
 			return <Image src="/connectors/obsidian.svg" alt="Obsidian" {...imgProps} />;
 		case EnumConnectorName.COMPOSIO_GOOGLE_DRIVE_CONNECTOR:
diff --git a/surfsense_web/contracts/types/connector.types.ts b/surfsense_web/contracts/types/connector.types.ts
index b83e05dcc..269941375 100644
--- a/surfsense_web/contracts/types/connector.types.ts
+++ b/surfsense_web/contracts/types/connector.types.ts
@@ -30,6 +30,7 @@ export const searchSourceConnectorTypeEnum = z.enum([
 	"DROPBOX_CONNECTOR",
 	"MCP_CONNECTOR",
 	"OBSIDIAN_CONNECTOR",
+	"LOCAL_FOLDER_CONNECTOR",
 	"COMPOSIO_GOOGLE_DRIVE_CONNECTOR",
 	"COMPOSIO_GMAIL_CONNECTOR",
 	"COMPOSIO_GOOGLE_CALENDAR_CONNECTOR",

From 5eeee99bb1be4f118e8417f31c3fe0322d558fb4 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 11:40:04 +0530
Subject: [PATCH 18/70] feat: enhance Local Folder connector with version
 history and folder sync capabilities

---
 .../(manage)/components/DocumentTypeIcon.tsx  |   1 +
 .../components/local-folder-connect-form.tsx  | 272 ++++++++++++++++++
 .../connect-forms/connector-benefits.ts       |   8 +
 .../connector-popup/connect-forms/index.tsx   |   4 +-
 .../components/local-folder-config.tsx        | 163 +++++++++++
 .../connector-configs/index.tsx               |   3 +
 .../utils/connector-document-mapping.ts       |   1 +
 .../components/documents/version-history.tsx  | 185 ++++++++++++
 .../contracts/types/document.types.ts         |   1 +
 surfsense_web/hooks/use-folder-sync.ts        |  41 +++
 .../lib/apis/connectors-api.service.ts        |  12 +
 .../lib/apis/documents-api.service.ts         |  16 ++
 surfsense_web/lib/connectors/utils.ts         |   1 +
 surfsense_web/types/window.d.ts               |  35 +++
 14 files changed, 742 insertions(+), 1 deletion(-)
 create mode 100644 surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/local-folder-connect-form.tsx
 create mode 100644 surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/local-folder-config.tsx
 create mode 100644 surfsense_web/components/documents/version-history.tsx
 create mode 100644 surfsense_web/hooks/use-folder-sync.ts

diff --git a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentTypeIcon.tsx b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentTypeIcon.tsx
index 43108c745..5c03d96fa 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentTypeIcon.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentTypeIcon.tsx
@@ -35,6 +35,7 @@ export function getDocumentTypeLabel(type: string): string {
 		BOOKSTACK_CONNECTOR: "BookStack",
 		CIRCLEBACK: "Circleback",
 		OBSIDIAN_CONNECTOR: "Obsidian",
+		LOCAL_FOLDER_FILE: "Local Folder",
 		SURFSENSE_DOCS: "SurfSense Docs",
 		NOTE: "Note",
 		COMPOSIO_GOOGLE_DRIVE_CONNECTOR: "Composio Google Drive",
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/local-folder-connect-form.tsx b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/local-folder-connect-form.tsx
new file mode 100644
index 000000000..2e893c1c0
--- /dev/null
+++ b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/local-folder-connect-form.tsx
@@ -0,0 +1,272 @@
+"use client";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import { FolderSync, Info } from "lucide-react";
+import type { FC } from "react";
+import { useRef } from "react";
+import { useForm } from "react-hook-form";
+import * as z from "zod";
+import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
+import { Button } from "@/components/ui/button";
+import {
+	Form,
+	FormControl,
+	FormDescription,
+	FormField,
+	FormItem,
+	FormLabel,
+	FormMessage,
+} from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import { EnumConnectorName } from "@/contracts/enums/connector";
+import { getConnectorBenefits } from "../connector-benefits";
+import type { ConnectFormProps } from "../index";
+
+const localFolderFormSchema = z.object({
+	name: z.string().min(3, {
+		message: "Connector name must be at least 3 characters.",
+	}),
+	folder_path: z.string().min(1, {
+		message: "Folder path is required.",
+	}),
+	folder_name: z.string().min(1, {
+		message: "Folder name is required.",
+	}),
+	exclude_patterns: z.string().optional(),
+	file_extensions: z.string().optional(),
+});
+
+type LocalFolderFormValues = z.infer<typeof localFolderFormSchema>;
+
+export const LocalFolderConnectForm: FC<ConnectFormProps> = ({ onSubmit, isSubmitting }) => {
+	const isSubmittingRef = useRef(false);
+	const isElectron = typeof window !== "undefined" && !!window.electronAPI;
+
+	const form = useForm<LocalFolderFormValues>({
+		resolver: zodResolver(localFolderFormSchema),
+		defaultValues: {
+			name: "Local Folder",
+			folder_path: "",
+			folder_name: "",
+			exclude_patterns: "node_modules,.git,.DS_Store",
+			file_extensions: "",
+		},
+	});
+
+	const handleBrowse = async () => {
+		if (!isElectron) return;
+		const selected = await window.electronAPI!.selectFolder();
+		if (selected) {
+			form.setValue("folder_path", selected);
+			const folderName = selected.split(/[\\/]/).pop() || "folder";
+			if (!form.getValues("folder_name")) {
+				form.setValue("folder_name", folderName);
+			}
+			if (form.getValues("name") === "Local Folder") {
+				form.setValue("name", folderName);
+			}
+		}
+	};
+
+	const handleSubmit = async (values: LocalFolderFormValues) => {
+		if (isSubmittingRef.current || isSubmitting) return;
+		isSubmittingRef.current = true;
+
+		try {
+			const excludePatterns = values.exclude_patterns
+				? values.exclude_patterns
+						.split(",")
+						.map((p) => p.trim())
+						.filter(Boolean)
+				: [];
+
+			const fileExtensions = values.file_extensions
+				? values.file_extensions
+						.split(",")
+						.map((e) => {
+							const ext = e.trim();
+							return ext.startsWith(".") ? ext : `.${ext}`;
+						})
+						.filter(Boolean)
+				: null;
+
+			await onSubmit({
+				name: values.name,
+				connector_type: EnumConnectorName.LOCAL_FOLDER_CONNECTOR,
+				config: {
+					folder_path: values.folder_path,
+					folder_name: values.folder_name,
+					exclude_patterns: excludePatterns,
+					file_extensions: fileExtensions,
+				},
+				is_indexable: true,
+				is_active: true,
+				last_indexed_at: null,
+				periodic_indexing_enabled: false,
+				indexing_frequency_minutes: null,
+				next_scheduled_at: null,
+			});
+		} finally {
+			isSubmittingRef.current = false;
+		}
+	};
+
+	return (
+		<div className="space-y-6 pb-6">
+			<Alert className="bg-blue-500/10 dark:bg-blue-500/10 border-blue-500/30 p-2 sm:p-3">
+				<Info className="size-4 shrink-0 text-blue-500" />
+				<AlertTitle className="text-xs sm:text-sm">Desktop App Required</AlertTitle>
+				<AlertDescription className="text-[10px] sm:text-xs">
+					Real-time file watching is powered by the SurfSense desktop app. Files are
+					automatically synced whenever changes are detected.
+				</AlertDescription>
+			</Alert>
+
+			<div className="rounded-xl border border-border bg-slate-400/5 dark:bg-white/5 p-3 sm:p-6 space-y-3 sm:space-y-4">
+				<Form {...form}>
+					<form
+						id="local-folder-connect-form"
+						onSubmit={form.handleSubmit(handleSubmit)}
+						className="space-y-4 sm:space-y-6"
+					>
+						<FormField
+							control={form.control}
+							name="name"
+							render={({ field }) => (
+								<FormItem>
+									<FormLabel className="text-xs sm:text-sm">Connector Name</FormLabel>
+									<FormControl>
+										<Input
+											placeholder="My Documents"
+											className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40"
+											disabled={isSubmitting}
+											{...field}
+										/>
+									</FormControl>
+									<FormMessage />
+								</FormItem>
+							)}
+						/>
+
+						<FormField
+							control={form.control}
+							name="folder_path"
+							render={({ field }) => (
+								<FormItem>
+									<FormLabel className="text-xs sm:text-sm">Folder Path</FormLabel>
+									<div className="flex gap-2">
+										<FormControl>
+											<Input
+												placeholder="/path/to/your/folder"
+												className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40 font-mono flex-1"
+												disabled={isSubmitting}
+												{...field}
+											/>
+										</FormControl>
+										{isElectron && (
+											<Button
+												type="button"
+												variant="outline"
+												size="sm"
+												onClick={handleBrowse}
+												disabled={isSubmitting}
+												className="shrink-0"
+											>
+												<FolderSync className="h-4 w-4 mr-1" />
+												Browse
+											</Button>
+										)}
+									</div>
+									<FormDescription className="text-[10px] sm:text-xs">
+										The absolute path to the folder to watch and sync.
+									</FormDescription>
+									<FormMessage />
+								</FormItem>
+							)}
+						/>
+
+						<FormField
+							control={form.control}
+							name="folder_name"
+							render={({ field }) => (
+								<FormItem>
+									<FormLabel className="text-xs sm:text-sm">Display Name</FormLabel>
+									<FormControl>
+										<Input
+											placeholder="My Notes"
+											className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40"
+											disabled={isSubmitting}
+											{...field}
+										/>
+									</FormControl>
+									<FormDescription className="text-[10px] sm:text-xs">
+										A friendly name shown in the documents sidebar.
+									</FormDescription>
+									<FormMessage />
+								</FormItem>
+							)}
+						/>
+
+						<FormField
+							control={form.control}
+							name="exclude_patterns"
+							render={({ field }) => (
+								<FormItem>
+									<FormLabel className="text-xs sm:text-sm">Exclude Patterns</FormLabel>
+									<FormControl>
+										<Input
+											placeholder="node_modules,.git,.DS_Store"
+											className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40 font-mono"
+											disabled={isSubmitting}
+											{...field}
+										/>
+									</FormControl>
+									<FormDescription className="text-[10px] sm:text-xs">
+										Comma-separated patterns of directories/files to exclude.
+									</FormDescription>
+									<FormMessage />
+								</FormItem>
+							)}
+						/>
+
+						<FormField
+							control={form.control}
+							name="file_extensions"
+							render={({ field }) => (
+								<FormItem>
+									<FormLabel className="text-xs sm:text-sm">File Extensions (optional)</FormLabel>
+									<FormControl>
+										<Input
+											placeholder=".md,.txt,.rst"
+											className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40 font-mono"
+											disabled={isSubmitting}
+											{...field}
+										/>
+									</FormControl>
+									<FormDescription className="text-[10px] sm:text-xs">
+										Leave empty to index all supported files, or specify comma-separated extensions.
+									</FormDescription>
+									<FormMessage />
+								</FormItem>
+							)}
+						/>
+
+					</form>
+				</Form>
+			</div>
+
+			{getConnectorBenefits(EnumConnectorName.LOCAL_FOLDER_CONNECTOR) && (
+				<div className="rounded-xl border border-border bg-slate-400/5 dark:bg-white/5 px-3 sm:px-6 py-4 space-y-2">
+					<h4 className="text-xs sm:text-sm font-medium">
+						What you get with Local Folder sync:
+					</h4>
+					<ul className="list-disc pl-5 text-[10px] sm:text-xs text-muted-foreground space-y-1">
+						{getConnectorBenefits(EnumConnectorName.LOCAL_FOLDER_CONNECTOR)?.map(
+							(benefit) => <li key={benefit}>{benefit}</li>
+						)}
+					</ul>
+				</div>
+			)}
+		</div>
+	);
+};
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/connector-benefits.ts b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/connector-benefits.ts
index 0dc093100..40c6a7fdd 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/connector-benefits.ts
+++ b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/connector-benefits.ts
@@ -111,6 +111,14 @@ export function getConnectorBenefits(connectorType: string): string[] | null {
 			"Incremental sync - only changed files are re-indexed",
 			"Full support for your vault's folder structure",
 		],
+		LOCAL_FOLDER_CONNECTOR: [
+			"Watch local folders for real-time changes via the desktop app",
+			"Automatic change detection — only modified files are re-indexed",
+			"Version history with up to 20 snapshots per document",
+			"Mirrors your folder structure in the SurfSense sidebar",
+			"Supports any text-based file format",
+			"Works as a periodic sync fallback when the desktop app is not running",
+		],
 	};
 
 	return benefits[connectorType] || null;
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/index.tsx b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/index.tsx
index 37d4ad5d8..116893399 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/index.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/index.tsx
@@ -7,6 +7,7 @@ import { GithubConnectForm } from "./components/github-connect-form";
 import { LinkupApiConnectForm } from "./components/linkup-api-connect-form";
 import { LumaConnectForm } from "./components/luma-connect-form";
 import { MCPConnectForm } from "./components/mcp-connect-form";
+import { LocalFolderConnectForm } from "./components/local-folder-connect-form";
 import { ObsidianConnectForm } from "./components/obsidian-connect-form";
 import { TavilyApiConnectForm } from "./components/tavily-api-connect-form";
 
@@ -58,7 +59,8 @@ export function getConnectFormComponent(connectorType: string): ConnectFormCompo
 			return MCPConnectForm;
 		case "OBSIDIAN_CONNECTOR":
 			return ObsidianConnectForm;
-		// Add other connector types here as needed
+		case "LOCAL_FOLDER_CONNECTOR":
+			return LocalFolderConnectForm;
 		default:
 			return null;
 	}
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/local-folder-config.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/local-folder-config.tsx
new file mode 100644
index 000000000..cb4295079
--- /dev/null
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/local-folder-config.tsx
@@ -0,0 +1,163 @@
+"use client";
+
+import type { FC } from "react";
+import { useState } from "react";
+import { FolderSync } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import type { ConnectorConfigProps } from "../index";
+
+export const LocalFolderConfig: FC<ConnectorConfigProps> = ({
+	connector,
+	onConfigChange,
+	onNameChange,
+}) => {
+	const isElectron = typeof window !== "undefined" && !!window.electronAPI;
+
+	const [folderPath, setFolderPath] = useState<string>(
+		(connector.config?.folder_path as string) || ""
+	);
+	const [folderName, setFolderName] = useState<string>(
+		(connector.config?.folder_name as string) || ""
+	);
+	const [excludePatterns, setExcludePatterns] = useState<string>(() => {
+		const patterns = connector.config?.exclude_patterns;
+		if (Array.isArray(patterns)) {
+			return patterns.join(", ");
+		}
+		return (patterns as string) || "node_modules, .git, .DS_Store";
+	});
+	const [fileExtensions, setFileExtensions] = useState<string>(() => {
+		const exts = connector.config?.file_extensions;
+		if (Array.isArray(exts)) {
+			return exts.join(", ");
+		}
+		return (exts as string) || "";
+	});
+	const [name, setName] = useState<string>(connector.name || "");
+
+	const handleFolderPathChange = (value: string) => {
+		setFolderPath(value);
+		onConfigChange?.({ ...connector.config, folder_path: value });
+	};
+
+	const handleFolderNameChange = (value: string) => {
+		setFolderName(value);
+		onConfigChange?.({ ...connector.config, folder_name: value });
+	};
+
+	const handleExcludePatternsChange = (value: string) => {
+		setExcludePatterns(value);
+		const arr = value
+			.split(",")
+			.map((p) => p.trim())
+			.filter(Boolean);
+		onConfigChange?.({ ...connector.config, exclude_patterns: arr });
+	};
+
+	const handleFileExtensionsChange = (value: string) => {
+		setFileExtensions(value);
+		const arr = value
+			? value
+					.split(",")
+					.map((e) => {
+						const ext = e.trim();
+						return ext.startsWith(".") ? ext : `.${ext}`;
+					})
+					.filter(Boolean)
+			: null;
+		onConfigChange?.({ ...connector.config, file_extensions: arr });
+	};
+
+	const handleNameChange = (value: string) => {
+		setName(value);
+		onNameChange?.(value);
+	};
+
+	const handleBrowse = async () => {
+		if (!isElectron) return;
+		const selected = await window.electronAPI!.selectFolder();
+		if (selected) {
+			handleFolderPathChange(selected);
+			const autoName = selected.split(/[\\/]/).pop() || "folder";
+			if (!folderName) handleFolderNameChange(autoName);
+		}
+	};
+
+	return (
+		<div className="space-y-6">
+			<div className="rounded-xl border border-border bg-slate-400/5 dark:bg-white/5 p-3 sm:p-6 space-y-3 sm:space-y-4">
+				<div className="space-y-2">
+					<Label className="text-xs sm:text-sm">Connector Name</Label>
+					<Input
+						value={name}
+						onChange={(e) => handleNameChange(e.target.value)}
+						placeholder="Local Folder"
+						className="border-slate-400/20 focus-visible:border-slate-400/40"
+					/>
+				</div>
+			</div>
+
+			<div className="rounded-xl border border-border bg-slate-400/5 dark:bg-white/5 p-3 sm:p-6 space-y-3 sm:space-y-4">
+				<h3 className="font-medium text-sm sm:text-base">Folder Configuration</h3>
+
+				<div className="space-y-4">
+					<div className="space-y-2">
+						<Label className="text-xs sm:text-sm">Folder Path</Label>
+						<div className="flex gap-2">
+							<Input
+								value={folderPath}
+								onChange={(e) => handleFolderPathChange(e.target.value)}
+								placeholder="/path/to/your/folder"
+								className="border-slate-400/20 focus-visible:border-slate-400/40 font-mono flex-1"
+							/>
+							{isElectron && (
+								<Button type="button" variant="outline" size="sm" onClick={handleBrowse} className="shrink-0">
+									<FolderSync className="h-4 w-4 mr-1" />
+									Browse
+								</Button>
+							)}
+						</div>
+					</div>
+
+					<div className="space-y-2">
+						<Label className="text-xs sm:text-sm">Display Name</Label>
+						<Input
+							value={folderName}
+							onChange={(e) => handleFolderNameChange(e.target.value)}
+							placeholder="My Notes"
+							className="border-slate-400/20 focus-visible:border-slate-400/40"
+						/>
+					</div>
+
+					<div className="space-y-2">
+						<Label className="text-xs sm:text-sm">Exclude Patterns</Label>
+						<Input
+							value={excludePatterns}
+							onChange={(e) => handleExcludePatternsChange(e.target.value)}
+							placeholder="node_modules, .git, .DS_Store"
+							className="border-slate-400/20 focus-visible:border-slate-400/40 font-mono"
+						/>
+						<p className="text-[10px] sm:text-xs text-muted-foreground">
+							Comma-separated patterns of directories/files to exclude.
+						</p>
+					</div>
+
+					<div className="space-y-2">
+						<Label className="text-xs sm:text-sm">File Extensions (optional)</Label>
+						<Input
+							value={fileExtensions}
+							onChange={(e) => handleFileExtensionsChange(e.target.value)}
+							placeholder=".md, .txt, .rst"
+							className="border-slate-400/20 focus-visible:border-slate-400/40 font-mono"
+						/>
+						<p className="text-[10px] sm:text-xs text-muted-foreground">
+							Leave empty to index all supported files.
+						</p>
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+};
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/index.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/index.tsx
index a63435260..3dc1891c8 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/index.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/index.tsx
@@ -19,6 +19,7 @@ import { JiraConfig } from "./components/jira-config";
 import { LinkupApiConfig } from "./components/linkup-api-config";
 import { LumaConfig } from "./components/luma-config";
 import { MCPConfig } from "./components/mcp-config";
+import { LocalFolderConfig } from "./components/local-folder-config";
 import { ObsidianConfig } from "./components/obsidian-config";
 import { OneDriveConfig } from "./components/onedrive-config";
 import { SlackConfig } from "./components/slack-config";
@@ -82,6 +83,8 @@ export function getConnectorConfigComponent(
 			return MCPConfig;
 		case "OBSIDIAN_CONNECTOR":
 			return ObsidianConfig;
+		case "LOCAL_FOLDER_CONNECTOR":
+			return LocalFolderConfig;
 		case "COMPOSIO_GOOGLE_DRIVE_CONNECTOR":
 			return ComposioDriveConfig;
 		case "COMPOSIO_GMAIL_CONNECTOR":
diff --git a/surfsense_web/components/assistant-ui/connector-popup/utils/connector-document-mapping.ts b/surfsense_web/components/assistant-ui/connector-popup/utils/connector-document-mapping.ts
index f924bb15f..dd5978002 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/utils/connector-document-mapping.ts
+++ b/surfsense_web/components/assistant-ui/connector-popup/utils/connector-document-mapping.ts
@@ -29,6 +29,7 @@ export const CONNECTOR_TO_DOCUMENT_TYPE: Record<string, string> = {
 	BOOKSTACK_CONNECTOR: "BOOKSTACK_CONNECTOR",
 	CIRCLEBACK_CONNECTOR: "CIRCLEBACK",
 	OBSIDIAN_CONNECTOR: "OBSIDIAN_CONNECTOR",
+	LOCAL_FOLDER_CONNECTOR: "LOCAL_FOLDER_FILE",
 
 	// Special mappings (connector type differs from document type)
 	GOOGLE_DRIVE_CONNECTOR: "GOOGLE_DRIVE_FILE",
diff --git a/surfsense_web/components/documents/version-history.tsx b/surfsense_web/components/documents/version-history.tsx
new file mode 100644
index 000000000..29740e079
--- /dev/null
+++ b/surfsense_web/components/documents/version-history.tsx
@@ -0,0 +1,185 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { Clock, RotateCcw } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import {
+	Sheet,
+	SheetContent,
+	SheetHeader,
+	SheetTitle,
+	SheetTrigger,
+} from "@/components/ui/sheet";
+import { Spinner } from "@/components/ui/spinner";
+import { documentsApiService } from "@/lib/apis/documents-api.service";
+import { toast } from "sonner";
+
+interface DocumentVersionSummary {
+	version_number: number;
+	title: string;
+	content_hash: string;
+	created_at: string | null;
+}
+
+interface VersionHistoryProps {
+	documentId: number;
+	documentType: string;
+}
+
+export function VersionHistoryButton({ documentId, documentType }: VersionHistoryProps) {
+	const showVersionHistory = documentType === "LOCAL_FOLDER_FILE" || documentType === "OBSIDIAN_CONNECTOR";
+	if (!showVersionHistory) return null;
+
+	return (
+		<Sheet>
+			<SheetTrigger asChild>
+				<Button variant="ghost" size="sm" className="gap-1.5 text-xs">
+					<Clock className="h-3.5 w-3.5" />
+					Versions
+				</Button>
+			</SheetTrigger>
+			<SheetContent className="w-[400px] sm:w-[540px]">
+				<SheetHeader>
+					<SheetTitle>Version History</SheetTitle>
+				</SheetHeader>
+				<VersionHistoryPanel documentId={documentId} />
+			</SheetContent>
+		</Sheet>
+	);
+}
+
+function VersionHistoryPanel({ documentId }: { documentId: number }) {
+	const [versions, setVersions] = useState<DocumentVersionSummary[]>([]);
+	const [loading, setLoading] = useState(true);
+	const [selectedVersion, setSelectedVersion] = useState<number | null>(null);
+	const [versionContent, setVersionContent] = useState<string>("");
+	const [contentLoading, setContentLoading] = useState(false);
+	const [restoring, setRestoring] = useState(false);
+
+	const loadVersions = useCallback(async () => {
+		setLoading(true);
+		try {
+			const data = await documentsApiService.listDocumentVersions(documentId);
+			setVersions(data as DocumentVersionSummary[]);
+		} catch {
+			toast.error("Failed to load version history");
+		} finally {
+			setLoading(false);
+		}
+	}, [documentId]);
+
+	useEffect(() => {
+		loadVersions();
+	}, [loadVersions]);
+
+	const handleSelectVersion = async (versionNumber: number) => {
+		setSelectedVersion(versionNumber);
+		setContentLoading(true);
+		try {
+			const data = (await documentsApiService.getDocumentVersion(
+				documentId,
+				versionNumber
+			)) as { source_markdown: string };
+			setVersionContent(data.source_markdown || "");
+		} catch {
+			toast.error("Failed to load version content");
+		} finally {
+			setContentLoading(false);
+		}
+	};
+
+	const handleRestore = async (versionNumber: number) => {
+		setRestoring(true);
+		try {
+			await documentsApiService.restoreDocumentVersion(documentId, versionNumber);
+			toast.success(`Restored version ${versionNumber}`);
+			await loadVersions();
+		} catch {
+			toast.error("Failed to restore version");
+		} finally {
+			setRestoring(false);
+		}
+	};
+
+	if (loading) {
+		return (
+			<div className="flex items-center justify-center py-12">
+				<Spinner size="lg" className="text-muted-foreground" />
+			</div>
+		);
+	}
+
+	if (versions.length === 0) {
+		return (
+			<div className="flex flex-col items-center justify-center py-12 text-muted-foreground">
+				<Clock className="h-8 w-8 mb-2 opacity-50" />
+				<p className="text-sm">No version history available yet.</p>
+				<p className="text-xs mt-1">Versions are created when file content changes.</p>
+			</div>
+		);
+	}
+
+	return (
+		<div className="flex flex-col gap-4 pt-4 h-full">
+			<div className="flex-1 overflow-y-auto space-y-2">
+				{versions.map((v) => (
+					<div
+						key={v.version_number}
+						className={`rounded-lg border p-3 cursor-pointer transition-colors ${
+							selectedVersion === v.version_number
+								? "border-primary bg-primary/5"
+								: "border-border hover:border-primary/50"
+						}`}
+						onClick={() => handleSelectVersion(v.version_number)}
+					>
+						<div className="flex items-center justify-between">
+							<div className="space-y-1">
+								<p className="text-sm font-medium">Version {v.version_number}</p>
+								{v.created_at && (
+									<p className="text-xs text-muted-foreground">
+										{new Date(v.created_at).toLocaleString()}
+									</p>
+								)}
+								{v.title && (
+									<p className="text-xs text-muted-foreground truncate max-w-[200px]">
+										{v.title}
+									</p>
+								)}
+							</div>
+							<Button
+								variant="outline"
+								size="sm"
+								className="shrink-0 gap-1"
+								disabled={restoring}
+								onClick={(e) => {
+									e.stopPropagation();
+									handleRestore(v.version_number);
+								}}
+							>
+								<RotateCcw className="h-3 w-3" />
+								Restore
+							</Button>
+						</div>
+					</div>
+				))}
+			</div>
+
+			{selectedVersion !== null && (
+				<div className="border-t pt-4 max-h-[40vh] overflow-y-auto">
+					<h4 className="text-sm font-medium mb-2">
+						Preview — Version {selectedVersion}
+					</h4>
+					{contentLoading ? (
+						<div className="flex items-center justify-center py-6">
+							<Spinner size="sm" />
+						</div>
+					) : (
+						<pre className="text-xs whitespace-pre-wrap font-mono bg-muted/50 rounded-lg p-3 max-h-[30vh] overflow-y-auto">
+							{versionContent || "(empty)"}
+						</pre>
+					)}
+				</div>
+			)}
+		</div>
+	);
+}
diff --git a/surfsense_web/contracts/types/document.types.ts b/surfsense_web/contracts/types/document.types.ts
index 1a3326bae..c663d6115 100644
--- a/surfsense_web/contracts/types/document.types.ts
+++ b/surfsense_web/contracts/types/document.types.ts
@@ -26,6 +26,7 @@ export const documentTypeEnum = z.enum([
 	"BOOKSTACK_CONNECTOR",
 	"CIRCLEBACK",
 	"OBSIDIAN_CONNECTOR",
+	"LOCAL_FOLDER_FILE",
 	"SURFSENSE_DOCS",
 	"NOTE",
 	"COMPOSIO_GOOGLE_DRIVE_CONNECTOR",
diff --git a/surfsense_web/hooks/use-folder-sync.ts b/surfsense_web/hooks/use-folder-sync.ts
new file mode 100644
index 000000000..a35faf98f
--- /dev/null
+++ b/surfsense_web/hooks/use-folder-sync.ts
@@ -0,0 +1,41 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { connectorsApiService } from "@/lib/apis/connectors-api.service";
+
+const DEBOUNCE_MS = 2000;
+
+export function useFolderSync() {
+	const pendingRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+	useEffect(() => {
+		const api = typeof window !== "undefined" ? window.electronAPI : null;
+		if (!api?.onFileChanged) return;
+
+		const cleanup = api.onFileChanged((event) => {
+			const key = `${event.connectorId}:${event.fullPath}`;
+
+			const existing = pendingRef.current.get(key);
+			if (existing) clearTimeout(existing);
+
+			const timeout = setTimeout(async () => {
+				pendingRef.current.delete(key);
+				try {
+					await connectorsApiService.indexFile(event.connectorId, event.fullPath);
+				} catch (err) {
+					console.error("[FolderSync] Failed to trigger re-index:", err);
+				}
+			}, DEBOUNCE_MS);
+
+			pendingRef.current.set(key, timeout);
+		});
+
+		return () => {
+			cleanup();
+			for (const timeout of pendingRef.current.values()) {
+				clearTimeout(timeout);
+			}
+			pendingRef.current.clear();
+		};
+	}, []);
+}
diff --git a/surfsense_web/lib/apis/connectors-api.service.ts b/surfsense_web/lib/apis/connectors-api.service.ts
index abd16c7a7..f2722df70 100644
--- a/surfsense_web/lib/apis/connectors-api.service.ts
+++ b/surfsense_web/lib/apis/connectors-api.service.ts
@@ -404,6 +404,18 @@ class ConnectorsApiService {
 			listDiscordChannelsResponse
 		);
 	};
+
+	// =============================================================================
+	// Local Folder Connector Methods
+	// =============================================================================
+
+	indexFile = async (connectorId: number, filePath: string) => {
+		return baseApiService.post(
+			`/api/v1/search-source-connectors/${connectorId}/index-file`,
+			undefined,
+			{ body: { file_path: filePath } }
+		);
+	};
 }
 
 export type { SlackChannel, DiscordChannel };
diff --git a/surfsense_web/lib/apis/documents-api.service.ts b/surfsense_web/lib/apis/documents-api.service.ts
index 14a247032..d4a80f8a0 100644
--- a/surfsense_web/lib/apis/documents-api.service.ts
+++ b/surfsense_web/lib/apis/documents-api.service.ts
@@ -379,6 +379,22 @@ class DocumentsApiService {
 		});
 	};
 
+	listDocumentVersions = async (documentId: number) => {
+		return baseApiService.get(`/api/v1/documents/${documentId}/versions`);
+	};
+
+	getDocumentVersion = async (documentId: number, versionNumber: number) => {
+		return baseApiService.get(
+			`/api/v1/documents/${documentId}/versions/${versionNumber}`
+		);
+	};
+
+	restoreDocumentVersion = async (documentId: number, versionNumber: number) => {
+		return baseApiService.post(
+			`/api/v1/documents/${documentId}/versions/${versionNumber}/restore`
+		);
+	};
+
 	/**
 	 * Delete a document
 	 */
diff --git a/surfsense_web/lib/connectors/utils.ts b/surfsense_web/lib/connectors/utils.ts
index 90f7f5d21..6ce78be67 100644
--- a/surfsense_web/lib/connectors/utils.ts
+++ b/surfsense_web/lib/connectors/utils.ts
@@ -30,6 +30,7 @@ export const getConnectorTypeDisplay = (type: string): string => {
 		YOUTUBE_CONNECTOR: "YouTube",
 		CIRCLEBACK_CONNECTOR: "Circleback",
 		OBSIDIAN_CONNECTOR: "Obsidian",
+		LOCAL_FOLDER_CONNECTOR: "Local Folder",
 		DROPBOX_CONNECTOR: "Dropbox",
 		MCP_CONNECTOR: "MCP Server",
 	};
diff --git a/surfsense_web/types/window.d.ts b/surfsense_web/types/window.d.ts
index 9cf1aa596..921449b41 100644
--- a/surfsense_web/types/window.d.ts
+++ b/surfsense_web/types/window.d.ts
@@ -1,5 +1,30 @@
 import type { PostHog } from "posthog-js";
 
+interface WatchedFolderConfig {
+	path: string;
+	name: string;
+	excludePatterns: string[];
+	fileExtensions: string[] | null;
+	connectorId: number;
+	searchSpaceId: number;
+	active: boolean;
+}
+
+interface FolderSyncFileChangedEvent {
+	connectorId: number;
+	searchSpaceId: number;
+	folderPath: string;
+	relativePath: string;
+	fullPath: string;
+	action: "add" | "change" | "unlink";
+	timestamp: number;
+}
+
+interface FolderSyncWatcherReadyEvent {
+	connectorId: number;
+	folderPath: string;
+}
+
 interface ElectronAPI {
 	versions: {
 		electron: string;
@@ -14,6 +39,16 @@ interface ElectronAPI {
 	setQuickAskMode: (mode: string) => Promise<void>;
 	getQuickAskMode: () => Promise<string>;
 	replaceText: (text: string) => Promise<void>;
+	// Folder sync
+	selectFolder: () => Promise<string | null>;
+	addWatchedFolder: (config: WatchedFolderConfig) => Promise<WatchedFolderConfig[]>;
+	removeWatchedFolder: (folderPath: string) => Promise<WatchedFolderConfig[]>;
+	getWatchedFolders: () => Promise<WatchedFolderConfig[]>;
+	getWatcherStatus: () => Promise<{ path: string; active: boolean; watching: boolean }[]>;
+	onFileChanged: (callback: (data: FolderSyncFileChangedEvent) => void) => () => void;
+	onWatcherReady: (callback: (data: FolderSyncWatcherReadyEvent) => void) => () => void;
+	pauseWatcher: () => Promise<void>;
+	resumeWatcher: () => Promise<void>;
 }
 
 declare global {

From b93da843dc6125434d712ad8881bf248906782d1 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 11:55:29 +0530
Subject: [PATCH 19/70] feat: implement mtime tracking and synchronization for
 folder watcher

---
 .../src/modules/folder-watcher.ts             | 172 +++++++++++++++++-
 1 file changed, 164 insertions(+), 8 deletions(-)

diff --git a/surfsense_desktop/src/modules/folder-watcher.ts b/surfsense_desktop/src/modules/folder-watcher.ts
index bfd2136c9..072ae7b3f 100644
--- a/surfsense_desktop/src/modules/folder-watcher.ts
+++ b/surfsense_desktop/src/modules/folder-watcher.ts
@@ -1,5 +1,5 @@
 import { BrowserWindow, dialog } from 'electron';
-import chokidar from 'chokidar';
+import chokidar, { type FSWatcher } from 'chokidar';
 import * as path from 'path';
 import * as fs from 'fs';
 import { IPC_CHANNELS } from '../ipc/channels';
@@ -16,13 +16,24 @@ export interface WatchedFolderConfig {
 
 interface WatcherEntry {
   config: WatchedFolderConfig;
-  watcher: chokidar.FSWatcher | null;
+  watcher: FSWatcher | null;
 }
 
+type MtimeMap = Record<string, number>;
+
 const STORE_KEY = 'watchedFolders';
+const MTIME_TOLERANCE_S = 1.0;
+
 let store: any = null;
+let mtimeStore: any = null;
 let watchers: Map<string, WatcherEntry> = new Map();
 
+/**
+ * In-memory cache of mtime maps, keyed by folder path.
+ * Persisted to electron-store on mutation.
+ */
+const mtimeMaps: Map<string, MtimeMap> = new Map();
+
 async function getStore() {
   if (!store) {
     const { default: Store } = await import('electron-store');
@@ -36,6 +47,73 @@ async function getStore() {
   return store;
 }
 
+async function getMtimeStore() {
+  if (!mtimeStore) {
+    const { default: Store } = await import('electron-store');
+    mtimeStore = new Store({
+      name: 'folder-mtime-maps',
+      defaults: {} as Record<string, MtimeMap>,
+    });
+  }
+  return mtimeStore;
+}
+
+function loadMtimeMap(folderPath: string): MtimeMap {
+  return mtimeMaps.get(folderPath) ?? {};
+}
+
+function persistMtimeMap(folderPath: string) {
+  const map = mtimeMaps.get(folderPath) ?? {};
+  getMtimeStore().then((s) => s.set(folderPath, map));
+}
+
+function walkFolderMtimes(config: WatchedFolderConfig): MtimeMap {
+  const root = config.path;
+  const result: MtimeMap = {};
+  const excludes = new Set(config.excludePatterns);
+
+  function walk(dir: string) {
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const name = entry.name;
+
+      // Skip dotfiles/dotdirs and excluded names
+      if (name.startsWith('.') || excludes.has(name)) continue;
+
+      const full = path.join(dir, name);
+
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile()) {
+        if (
+          config.fileExtensions &&
+          config.fileExtensions.length > 0
+        ) {
+          const ext = path.extname(name).toLowerCase();
+          if (!config.fileExtensions.includes(ext)) continue;
+        }
+
+        try {
+          const stat = fs.statSync(full);
+          const rel = path.relative(root, full);
+          result[rel] = stat.mtimeMs;
+        } catch {
+          // File may have been removed between readdir and stat
+        }
+      }
+    }
+  }
+
+  walk(root);
+  return result;
+}
+
 function getMainWindow(): BrowserWindow | null {
   const windows = BrowserWindow.getAllWindows();
   return windows.length > 0 ? windows[0] : null;
@@ -48,11 +126,16 @@ function sendToRenderer(channel: string, data: any) {
   }
 }
 
-function startWatcher(config: WatchedFolderConfig) {
+async function startWatcher(config: WatchedFolderConfig) {
   if (watchers.has(config.path)) {
     return;
   }
 
+  // Load persisted mtime map into memory before starting the watcher
+  const ms = await getMtimeStore();
+  const storedMap: MtimeMap = ms.get(config.path) ?? {};
+  mtimeMaps.set(config.path, { ...storedMap });
+
   const ignored = [
     /(^|[/\\])\../, // dotfiles by default
     ...config.excludePatterns.map((p) => `**/${p}/**`),
@@ -60,7 +143,7 @@ function startWatcher(config: WatchedFolderConfig) {
 
   const watcher = chokidar.watch(config.path, {
     persistent: true,
-    ignoreInitial: false,
+    ignoreInitial: true,
     awaitWriteFinish: {
       stabilityThreshold: 500,
       pollInterval: 100,
@@ -72,6 +155,58 @@ function startWatcher(config: WatchedFolderConfig) {
 
   watcher.on('ready', () => {
     ready = true;
+
+    // Detect offline changes by diffing current filesystem against stored mtime map
+    const currentMap = walkFolderMtimes(config);
+    const storedSnapshot = loadMtimeMap(config.path);
+    const now = Date.now();
+
+    for (const [rel, currentMtime] of Object.entries(currentMap)) {
+      const storedMtime = storedSnapshot[rel];
+      if (storedMtime === undefined) {
+        // New file added while app was closed
+        sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, {
+          connectorId: config.connectorId,
+          searchSpaceId: config.searchSpaceId,
+          folderPath: config.path,
+          relativePath: rel,
+          fullPath: path.join(config.path, rel),
+          action: 'add',
+          timestamp: now,
+        });
+      } else if (Math.abs(currentMtime - storedMtime) >= MTIME_TOLERANCE_S * 1000) {
+        // File modified while app was closed
+        sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, {
+          connectorId: config.connectorId,
+          searchSpaceId: config.searchSpaceId,
+          folderPath: config.path,
+          relativePath: rel,
+          fullPath: path.join(config.path, rel),
+          action: 'change',
+          timestamp: now,
+        });
+      }
+    }
+
+    for (const rel of Object.keys(storedSnapshot)) {
+      if (!(rel in currentMap)) {
+        // File deleted while app was closed
+        sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, {
+          connectorId: config.connectorId,
+          searchSpaceId: config.searchSpaceId,
+          folderPath: config.path,
+          relativePath: rel,
+          fullPath: path.join(config.path, rel),
+          action: 'unlink',
+          timestamp: now,
+        });
+      }
+    }
+
+    // Replace stored map with current filesystem state
+    mtimeMaps.set(config.path, currentMap);
+    persistMtimeMap(config.path);
+
     sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_WATCHER_READY, {
       connectorId: config.connectorId,
       folderPath: config.path,
@@ -91,6 +226,21 @@ function startWatcher(config: WatchedFolderConfig) {
       if (!config.fileExtensions.includes(ext)) return;
     }
 
+    // Keep mtime map in sync with live changes
+    const map = mtimeMaps.get(config.path);
+    if (map) {
+      if (action === 'unlink') {
+        delete map[relativePath];
+      } else {
+        try {
+          map[relativePath] = fs.statSync(filePath).mtimeMs;
+        } catch {
+          // File may have been removed between event and stat
+        }
+      }
+      persistMtimeMap(config.path);
+    }
+
     sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, {
       connectorId: config.connectorId,
       searchSpaceId: config.searchSpaceId,
@@ -110,6 +260,7 @@ function startWatcher(config: WatchedFolderConfig) {
 }
 
 function stopWatcher(folderPath: string) {
+  persistMtimeMap(folderPath);
   const entry = watchers.get(folderPath);
   if (entry?.watcher) {
     entry.watcher.close();
@@ -144,7 +295,7 @@ export async function addWatchedFolder(
   s.set(STORE_KEY, folders);
 
   if (config.active) {
-    startWatcher(config);
+    await startWatcher(config);
   }
 
   return folders;
@@ -160,6 +311,11 @@ export async function removeWatchedFolder(
 
   stopWatcher(folderPath);
 
+  // Clean up persisted mtime map for this folder
+  mtimeMaps.delete(folderPath);
+  const ms = await getMtimeStore();
+  ms.delete(folderPath);
+
   return updated;
 }
 
@@ -190,9 +346,9 @@ export async function pauseWatcher(): Promise<void> {
 }
 
 export async function resumeWatcher(): Promise<void> {
-  for (const [folderPath, entry] of watchers) {
+  for (const [, entry] of watchers) {
     if (!entry.watcher && entry.config.active) {
-      startWatcher(entry.config);
+      await startWatcher(entry.config);
     }
   }
 }
@@ -203,7 +359,7 @@ export async function registerFolderWatcher(): Promise<void> {
 
   for (const config of folders) {
     if (config.active && fs.existsSync(config.path)) {
-      startWatcher(config);
+      await startWatcher(config);
     }
   }
 }

From 543b8b9376eb4fd89698deffdfde0f6d9e69a2e8 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 12:08:18 +0530
Subject: [PATCH 20/70] feat: add real-time folder watcher registration and
 unregistration for Local Folder connector

---
 .../hooks/use-connector-dialog.ts             | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/surfsense_web/components/assistant-ui/connector-popup/hooks/use-connector-dialog.ts b/surfsense_web/components/assistant-ui/connector-popup/hooks/use-connector-dialog.ts
index 6543bbd72..2404b8eb5 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/hooks/use-connector-dialog.ts
+++ b/surfsense_web/components/assistant-ui/connector-popup/hooks/use-connector-dialog.ts
@@ -586,6 +586,23 @@ export const useConnectorDialog = () => {
 									},
 								});
 
+								// Register folder watcher in Electron for real-time sync
+								if (
+									currentConnectorType === EnumConnectorName.LOCAL_FOLDER_CONNECTOR &&
+									window.electronAPI?.addWatchedFolder
+								) {
+									const cfg = connector.config || {};
+									await window.electronAPI.addWatchedFolder({
+										path: cfg.folder_path as string,
+										name: cfg.folder_name as string,
+										excludePatterns: (cfg.exclude_patterns as string[]) || [],
+										fileExtensions: (cfg.file_extensions as string[] | null) ?? null,
+										connectorId: connector.id,
+										searchSpaceId: Number(searchSpaceId),
+										active: true,
+									});
+								}
+
 								const successMessage =
 									currentConnectorType === "MCP_CONNECTOR"
 										? `${connector.name} added successfully`
@@ -1190,6 +1207,17 @@ export const useConnectorDialog = () => {
 					id: editingConnector.id,
 				});
 
+				// Unregister folder watcher in Electron when removing a Local Folder connector
+				if (
+					editingConnector.connector_type === EnumConnectorName.LOCAL_FOLDER_CONNECTOR &&
+					window.electronAPI?.removeWatchedFolder &&
+					editingConnector.config?.folder_path
+				) {
+					await window.electronAPI.removeWatchedFolder(
+						editingConnector.config.folder_path as string
+					);
+				}
+
 				// Track connector deleted event
 				trackConnectorDeleted(
 					Number(searchSpaceId),

From 8e58094a861a1517e6587a8e8f55182c3cffed7b Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 12:13:14 +0530
Subject: [PATCH 21/70] refactor: update permission checks in document and
 connector routes to use specific permission values

---
 surfsense_backend/app/routes/documents_routes.py            | 6 +++---
 .../app/routes/search_source_connectors_routes.py           | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index 9271d4630..2d999eae3 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -1156,7 +1156,7 @@ async def list_document_versions(
     if not document:
         raise HTTPException(status_code=404, detail="Document not found")
 
-    await check_permission(session, user, document.search_space_id, Permission.READ)
+    await check_permission(session, user, document.search_space_id, Permission.DOCUMENTS_READ.value)
 
     versions = (
         await session.execute(
@@ -1191,7 +1191,7 @@ async def get_document_version(
     if not document:
         raise HTTPException(status_code=404, detail="Document not found")
 
-    await check_permission(session, user, document.search_space_id, Permission.READ)
+    await check_permission(session, user, document.search_space_id, Permission.DOCUMENTS_READ.value)
 
     version = (
         await session.execute(
@@ -1229,7 +1229,7 @@ async def restore_document_version(
     if not document:
         raise HTTPException(status_code=404, detail="Document not found")
 
-    await check_permission(session, user, document.search_space_id, Permission.WRITE)
+    await check_permission(session, user, document.search_space_id, Permission.DOCUMENTS_UPDATE.value)
 
     version = (
         await session.execute(
diff --git a/surfsense_backend/app/routes/search_source_connectors_routes.py b/surfsense_backend/app/routes/search_source_connectors_routes.py
index 439d83ac1..5ea88c418 100644
--- a/surfsense_backend/app/routes/search_source_connectors_routes.py
+++ b/surfsense_backend/app/routes/search_source_connectors_routes.py
@@ -1355,7 +1355,7 @@ async def index_single_file(
     if not connector:
         raise HTTPException(status_code=404, detail="Local folder connector not found")
 
-    await check_permission(session, user, connector.search_space_id, Permission.WRITE)
+    await check_permission(session, user, connector.search_space_id, Permission.CONNECTORS_UPDATE.value)
 
     folder_path = connector.config.get("folder_path", "")
 

From 40ade4889e23b18ed43eaaa39a0489483fa5bbdc Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 21:01:31 +0530
Subject: [PATCH 22/70] feat: add LOCAL_FOLDER_FILE document type and update
 document_versions table management

---
 ...d_local_folder_connector_and_versioning.py | 33 +++++++------------
 1 file changed, 12 insertions(+), 21 deletions(-)

diff --git a/surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py b/surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py
index e97a4787c..a9da3beb4 100644
--- a/surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py
+++ b/surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py
@@ -1,4 +1,4 @@
-"""Add local folder connector enums and document_versions table
+"""Add LOCAL_FOLDER_FILE document type and document_versions table
 
 Revision ID: 117
 Revises: 116
@@ -21,23 +21,6 @@ PUBLICATION_NAME = "zero_publication"
 def upgrade() -> None:
     conn = op.get_bind()
 
-    # Add LOCAL_FOLDER_CONNECTOR to searchsourceconnectortype enum
-    op.execute(
-        """
-    DO $$
-    BEGIN
-        IF NOT EXISTS (
-            SELECT 1 FROM pg_type t
-            JOIN pg_enum e ON t.oid = e.enumtypid
-            WHERE t.typname = 'searchsourceconnectortype' AND e.enumlabel = 'LOCAL_FOLDER_CONNECTOR'
-        ) THEN
-            ALTER TYPE searchsourceconnectortype ADD VALUE 'LOCAL_FOLDER_CONNECTOR';
-        END IF;
-    END
-    $$;
-    """
-    )
-
     # Add LOCAL_FOLDER_FILE to documenttype enum
     op.execute(
         """
@@ -126,9 +109,17 @@ def downgrade() -> None:
         {"name": PUBLICATION_NAME},
     ).fetchone()
     if pub_exists:
-        op.execute(
-            f"ALTER PUBLICATION {PUBLICATION_NAME} DROP TABLE IF EXISTS document_versions"
-        )
+        already_in_pub = conn.execute(
+            sa.text(
+                "SELECT 1 FROM pg_publication_tables "
+                "WHERE pubname = :name AND tablename = 'document_versions'"
+            ),
+            {"name": PUBLICATION_NAME},
+        ).fetchone()
+        if already_in_pub:
+            op.execute(
+                f"ALTER PUBLICATION {PUBLICATION_NAME} DROP TABLE document_versions"
+            )
 
     op.execute("DROP INDEX IF EXISTS ix_document_versions_created_at")
     op.execute("DROP INDEX IF EXISTS ix_document_versions_document_id")

From 1ef0d913e7471c7df6b03b94647064bae76abb39 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 22:19:55 +0530
Subject: [PATCH 23/70] refactor: remove Local Folder connector components and
 related configurations from the UI

---
 .../(manage)/components/DocumentsFilters.tsx  |  43 ++-
 .../components/local-folder-connect-form.tsx  | 272 ------------------
 .../connect-forms/connector-benefits.ts       |   8 -
 .../connector-popup/connect-forms/index.tsx   |   3 -
 .../components/local-folder-config.tsx        | 163 -----------
 .../connector-configs/index.tsx               |   3 -
 .../views/connector-connect-view.tsx          |   1 -
 .../views/connector-edit-view.tsx             |   7 +-
 .../views/indexing-configuration-view.tsx     |   7 +-
 9 files changed, 35 insertions(+), 472 deletions(-)
 delete mode 100644 surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/local-folder-connect-form.tsx
 delete mode 100644 surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/local-folder-config.tsx

diff --git a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx
index b85af13b7..fcd3a39da 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { FolderPlus, ListFilter, Search, Upload, X } from "lucide-react";
+import { Eye, FolderPlus, ListFilter, Search, Upload, X } from "lucide-react";
 import { useTranslations } from "next-intl";
 import React, { useCallback, useMemo, useRef, useState } from "react";
 import { useDocumentUploadDialog } from "@/components/assistant-ui/document-upload-popup";
@@ -19,6 +19,7 @@ export function DocumentsFilters({
 	onToggleType,
 	activeTypes,
 	onCreateFolder,
+	onWatchFolder,
 }: {
 	typeCounts: Partial<Record<DocumentTypeEnum, number>>;
 	onSearch: (v: string) => void;
@@ -26,6 +27,7 @@ export function DocumentsFilters({
 	onToggleType: (type: DocumentTypeEnum, checked: boolean) => void;
 	activeTypes: DocumentTypeEnum[];
 	onCreateFolder?: () => void;
+	onWatchFolder?: () => void;
 }) {
 	const t = useTranslations("documents");
 	const id = React.useId();
@@ -214,17 +216,34 @@ export function DocumentsFilters({
 					</Tooltip>
 				)}
 
-				{/* Upload Button */}
-				<Button
-					data-joyride="upload-button"
-					onClick={openUploadDialog}
-					variant="outline"
-					size="sm"
-					className="h-9 shrink-0 gap-1.5 bg-white text-gray-700 border-white hover:bg-gray-50 dark:bg-white dark:text-gray-800 dark:hover:bg-gray-100"
-				>
-					<Upload size={14} />
-					<span>Upload</span>
-				</Button>
+			{/* Watch Folder Button (desktop only) */}
+			{onWatchFolder && (
+				<Tooltip>
+					<TooltipTrigger asChild>
+						<Button
+							variant="outline"
+							size="icon"
+							className="h-9 w-9 shrink-0 border-dashed border-sidebar-border text-sidebar-foreground/60 hover:text-sidebar-foreground hover:border-sidebar-border bg-sidebar"
+							onClick={onWatchFolder}
+						>
+							<Eye size={14} />
+						</Button>
+					</TooltipTrigger>
+					<TooltipContent>Watch folder</TooltipContent>
+				</Tooltip>
+			)}
+
+			{/* Upload Button */}
+			<Button
+				data-joyride="upload-button"
+				onClick={openUploadDialog}
+				variant="outline"
+				size="sm"
+				className="h-9 shrink-0 gap-1.5 bg-white text-gray-700 border-white hover:bg-gray-50 dark:bg-white dark:text-gray-800 dark:hover:bg-gray-100"
+			>
+				<Upload size={14} />
+				<span>Upload</span>
+			</Button>
 			</div>
 		</div>
 	);
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/local-folder-connect-form.tsx b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/local-folder-connect-form.tsx
deleted file mode 100644
index 2e893c1c0..000000000
--- a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/components/local-folder-connect-form.tsx
+++ /dev/null
@@ -1,272 +0,0 @@
-"use client";
-
-import { zodResolver } from "@hookform/resolvers/zod";
-import { FolderSync, Info } from "lucide-react";
-import type { FC } from "react";
-import { useRef } from "react";
-import { useForm } from "react-hook-form";
-import * as z from "zod";
-import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
-import { Button } from "@/components/ui/button";
-import {
-	Form,
-	FormControl,
-	FormDescription,
-	FormField,
-	FormItem,
-	FormLabel,
-	FormMessage,
-} from "@/components/ui/form";
-import { Input } from "@/components/ui/input";
-import { EnumConnectorName } from "@/contracts/enums/connector";
-import { getConnectorBenefits } from "../connector-benefits";
-import type { ConnectFormProps } from "../index";
-
-const localFolderFormSchema = z.object({
-	name: z.string().min(3, {
-		message: "Connector name must be at least 3 characters.",
-	}),
-	folder_path: z.string().min(1, {
-		message: "Folder path is required.",
-	}),
-	folder_name: z.string().min(1, {
-		message: "Folder name is required.",
-	}),
-	exclude_patterns: z.string().optional(),
-	file_extensions: z.string().optional(),
-});
-
-type LocalFolderFormValues = z.infer<typeof localFolderFormSchema>;
-
-export const LocalFolderConnectForm: FC<ConnectFormProps> = ({ onSubmit, isSubmitting }) => {
-	const isSubmittingRef = useRef(false);
-	const isElectron = typeof window !== "undefined" && !!window.electronAPI;
-
-	const form = useForm<LocalFolderFormValues>({
-		resolver: zodResolver(localFolderFormSchema),
-		defaultValues: {
-			name: "Local Folder",
-			folder_path: "",
-			folder_name: "",
-			exclude_patterns: "node_modules,.git,.DS_Store",
-			file_extensions: "",
-		},
-	});
-
-	const handleBrowse = async () => {
-		if (!isElectron) return;
-		const selected = await window.electronAPI!.selectFolder();
-		if (selected) {
-			form.setValue("folder_path", selected);
-			const folderName = selected.split(/[\\/]/).pop() || "folder";
-			if (!form.getValues("folder_name")) {
-				form.setValue("folder_name", folderName);
-			}
-			if (form.getValues("name") === "Local Folder") {
-				form.setValue("name", folderName);
-			}
-		}
-	};
-
-	const handleSubmit = async (values: LocalFolderFormValues) => {
-		if (isSubmittingRef.current || isSubmitting) return;
-		isSubmittingRef.current = true;
-
-		try {
-			const excludePatterns = values.exclude_patterns
-				? values.exclude_patterns
-						.split(",")
-						.map((p) => p.trim())
-						.filter(Boolean)
-				: [];
-
-			const fileExtensions = values.file_extensions
-				? values.file_extensions
-						.split(",")
-						.map((e) => {
-							const ext = e.trim();
-							return ext.startsWith(".") ? ext : `.${ext}`;
-						})
-						.filter(Boolean)
-				: null;
-
-			await onSubmit({
-				name: values.name,
-				connector_type: EnumConnectorName.LOCAL_FOLDER_CONNECTOR,
-				config: {
-					folder_path: values.folder_path,
-					folder_name: values.folder_name,
-					exclude_patterns: excludePatterns,
-					file_extensions: fileExtensions,
-				},
-				is_indexable: true,
-				is_active: true,
-				last_indexed_at: null,
-				periodic_indexing_enabled: false,
-				indexing_frequency_minutes: null,
-				next_scheduled_at: null,
-			});
-		} finally {
-			isSubmittingRef.current = false;
-		}
-	};
-
-	return (
-		<div className="space-y-6 pb-6">
-			<Alert className="bg-blue-500/10 dark:bg-blue-500/10 border-blue-500/30 p-2 sm:p-3">
-				<Info className="size-4 shrink-0 text-blue-500" />
-				<AlertTitle className="text-xs sm:text-sm">Desktop App Required</AlertTitle>
-				<AlertDescription className="text-[10px] sm:text-xs">
-					Real-time file watching is powered by the SurfSense desktop app. Files are
-					automatically synced whenever changes are detected.
-				</AlertDescription>
-			</Alert>
-
-			<div className="rounded-xl border border-border bg-slate-400/5 dark:bg-white/5 p-3 sm:p-6 space-y-3 sm:space-y-4">
-				<Form {...form}>
-					<form
-						id="local-folder-connect-form"
-						onSubmit={form.handleSubmit(handleSubmit)}
-						className="space-y-4 sm:space-y-6"
-					>
-						<FormField
-							control={form.control}
-							name="name"
-							render={({ field }) => (
-								<FormItem>
-									<FormLabel className="text-xs sm:text-sm">Connector Name</FormLabel>
-									<FormControl>
-										<Input
-											placeholder="My Documents"
-											className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40"
-											disabled={isSubmitting}
-											{...field}
-										/>
-									</FormControl>
-									<FormMessage />
-								</FormItem>
-							)}
-						/>
-
-						<FormField
-							control={form.control}
-							name="folder_path"
-							render={({ field }) => (
-								<FormItem>
-									<FormLabel className="text-xs sm:text-sm">Folder Path</FormLabel>
-									<div className="flex gap-2">
-										<FormControl>
-											<Input
-												placeholder="/path/to/your/folder"
-												className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40 font-mono flex-1"
-												disabled={isSubmitting}
-												{...field}
-											/>
-										</FormControl>
-										{isElectron && (
-											<Button
-												type="button"
-												variant="outline"
-												size="sm"
-												onClick={handleBrowse}
-												disabled={isSubmitting}
-												className="shrink-0"
-											>
-												<FolderSync className="h-4 w-4 mr-1" />
-												Browse
-											</Button>
-										)}
-									</div>
-									<FormDescription className="text-[10px] sm:text-xs">
-										The absolute path to the folder to watch and sync.
-									</FormDescription>
-									<FormMessage />
-								</FormItem>
-							)}
-						/>
-
-						<FormField
-							control={form.control}
-							name="folder_name"
-							render={({ field }) => (
-								<FormItem>
-									<FormLabel className="text-xs sm:text-sm">Display Name</FormLabel>
-									<FormControl>
-										<Input
-											placeholder="My Notes"
-											className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40"
-											disabled={isSubmitting}
-											{...field}
-										/>
-									</FormControl>
-									<FormDescription className="text-[10px] sm:text-xs">
-										A friendly name shown in the documents sidebar.
-									</FormDescription>
-									<FormMessage />
-								</FormItem>
-							)}
-						/>
-
-						<FormField
-							control={form.control}
-							name="exclude_patterns"
-							render={({ field }) => (
-								<FormItem>
-									<FormLabel className="text-xs sm:text-sm">Exclude Patterns</FormLabel>
-									<FormControl>
-										<Input
-											placeholder="node_modules,.git,.DS_Store"
-											className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40 font-mono"
-											disabled={isSubmitting}
-											{...field}
-										/>
-									</FormControl>
-									<FormDescription className="text-[10px] sm:text-xs">
-										Comma-separated patterns of directories/files to exclude.
-									</FormDescription>
-									<FormMessage />
-								</FormItem>
-							)}
-						/>
-
-						<FormField
-							control={form.control}
-							name="file_extensions"
-							render={({ field }) => (
-								<FormItem>
-									<FormLabel className="text-xs sm:text-sm">File Extensions (optional)</FormLabel>
-									<FormControl>
-										<Input
-											placeholder=".md,.txt,.rst"
-											className="h-8 sm:h-10 px-2 sm:px-3 text-xs sm:text-sm border-slate-400/20 focus-visible:border-slate-400/40 font-mono"
-											disabled={isSubmitting}
-											{...field}
-										/>
-									</FormControl>
-									<FormDescription className="text-[10px] sm:text-xs">
-										Leave empty to index all supported files, or specify comma-separated extensions.
-									</FormDescription>
-									<FormMessage />
-								</FormItem>
-							)}
-						/>
-
-					</form>
-				</Form>
-			</div>
-
-			{getConnectorBenefits(EnumConnectorName.LOCAL_FOLDER_CONNECTOR) && (
-				<div className="rounded-xl border border-border bg-slate-400/5 dark:bg-white/5 px-3 sm:px-6 py-4 space-y-2">
-					<h4 className="text-xs sm:text-sm font-medium">
-						What you get with Local Folder sync:
-					</h4>
-					<ul className="list-disc pl-5 text-[10px] sm:text-xs text-muted-foreground space-y-1">
-						{getConnectorBenefits(EnumConnectorName.LOCAL_FOLDER_CONNECTOR)?.map(
-							(benefit) => <li key={benefit}>{benefit}</li>
-						)}
-					</ul>
-				</div>
-			)}
-		</div>
-	);
-};
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/connector-benefits.ts b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/connector-benefits.ts
index 40c6a7fdd..0dc093100 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/connector-benefits.ts
+++ b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/connector-benefits.ts
@@ -111,14 +111,6 @@ export function getConnectorBenefits(connectorType: string): string[] | null {
 			"Incremental sync - only changed files are re-indexed",
 			"Full support for your vault's folder structure",
 		],
-		LOCAL_FOLDER_CONNECTOR: [
-			"Watch local folders for real-time changes via the desktop app",
-			"Automatic change detection — only modified files are re-indexed",
-			"Version history with up to 20 snapshots per document",
-			"Mirrors your folder structure in the SurfSense sidebar",
-			"Supports any text-based file format",
-			"Works as a periodic sync fallback when the desktop app is not running",
-		],
 	};
 
 	return benefits[connectorType] || null;
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/index.tsx b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/index.tsx
index 116893399..b6d813748 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connect-forms/index.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connect-forms/index.tsx
@@ -7,7 +7,6 @@ import { GithubConnectForm } from "./components/github-connect-form";
 import { LinkupApiConnectForm } from "./components/linkup-api-connect-form";
 import { LumaConnectForm } from "./components/luma-connect-form";
 import { MCPConnectForm } from "./components/mcp-connect-form";
-import { LocalFolderConnectForm } from "./components/local-folder-connect-form";
 import { ObsidianConnectForm } from "./components/obsidian-connect-form";
 import { TavilyApiConnectForm } from "./components/tavily-api-connect-form";
 
@@ -59,8 +58,6 @@ export function getConnectFormComponent(connectorType: string): ConnectFormCompo
 			return MCPConnectForm;
 		case "OBSIDIAN_CONNECTOR":
 			return ObsidianConnectForm;
-		case "LOCAL_FOLDER_CONNECTOR":
-			return LocalFolderConnectForm;
 		default:
 			return null;
 	}
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/local-folder-config.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/local-folder-config.tsx
deleted file mode 100644
index cb4295079..000000000
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/local-folder-config.tsx
+++ /dev/null
@@ -1,163 +0,0 @@
-"use client";
-
-import type { FC } from "react";
-import { useState } from "react";
-import { FolderSync } from "lucide-react";
-import { Button } from "@/components/ui/button";
-import { Input } from "@/components/ui/input";
-import { Label } from "@/components/ui/label";
-import type { ConnectorConfigProps } from "../index";
-
-export const LocalFolderConfig: FC<ConnectorConfigProps> = ({
-	connector,
-	onConfigChange,
-	onNameChange,
-}) => {
-	const isElectron = typeof window !== "undefined" && !!window.electronAPI;
-
-	const [folderPath, setFolderPath] = useState<string>(
-		(connector.config?.folder_path as string) || ""
-	);
-	const [folderName, setFolderName] = useState<string>(
-		(connector.config?.folder_name as string) || ""
-	);
-	const [excludePatterns, setExcludePatterns] = useState<string>(() => {
-		const patterns = connector.config?.exclude_patterns;
-		if (Array.isArray(patterns)) {
-			return patterns.join(", ");
-		}
-		return (patterns as string) || "node_modules, .git, .DS_Store";
-	});
-	const [fileExtensions, setFileExtensions] = useState<string>(() => {
-		const exts = connector.config?.file_extensions;
-		if (Array.isArray(exts)) {
-			return exts.join(", ");
-		}
-		return (exts as string) || "";
-	});
-	const [name, setName] = useState<string>(connector.name || "");
-
-	const handleFolderPathChange = (value: string) => {
-		setFolderPath(value);
-		onConfigChange?.({ ...connector.config, folder_path: value });
-	};
-
-	const handleFolderNameChange = (value: string) => {
-		setFolderName(value);
-		onConfigChange?.({ ...connector.config, folder_name: value });
-	};
-
-	const handleExcludePatternsChange = (value: string) => {
-		setExcludePatterns(value);
-		const arr = value
-			.split(",")
-			.map((p) => p.trim())
-			.filter(Boolean);
-		onConfigChange?.({ ...connector.config, exclude_patterns: arr });
-	};
-
-	const handleFileExtensionsChange = (value: string) => {
-		setFileExtensions(value);
-		const arr = value
-			? value
-					.split(",")
-					.map((e) => {
-						const ext = e.trim();
-						return ext.startsWith(".") ? ext : `.${ext}`;
-					})
-					.filter(Boolean)
-			: null;
-		onConfigChange?.({ ...connector.config, file_extensions: arr });
-	};
-
-	const handleNameChange = (value: string) => {
-		setName(value);
-		onNameChange?.(value);
-	};
-
-	const handleBrowse = async () => {
-		if (!isElectron) return;
-		const selected = await window.electronAPI!.selectFolder();
-		if (selected) {
-			handleFolderPathChange(selected);
-			const autoName = selected.split(/[\\/]/).pop() || "folder";
-			if (!folderName) handleFolderNameChange(autoName);
-		}
-	};
-
-	return (
-		<div className="space-y-6">
-			<div className="rounded-xl border border-border bg-slate-400/5 dark:bg-white/5 p-3 sm:p-6 space-y-3 sm:space-y-4">
-				<div className="space-y-2">
-					<Label className="text-xs sm:text-sm">Connector Name</Label>
-					<Input
-						value={name}
-						onChange={(e) => handleNameChange(e.target.value)}
-						placeholder="Local Folder"
-						className="border-slate-400/20 focus-visible:border-slate-400/40"
-					/>
-				</div>
-			</div>
-
-			<div className="rounded-xl border border-border bg-slate-400/5 dark:bg-white/5 p-3 sm:p-6 space-y-3 sm:space-y-4">
-				<h3 className="font-medium text-sm sm:text-base">Folder Configuration</h3>
-
-				<div className="space-y-4">
-					<div className="space-y-2">
-						<Label className="text-xs sm:text-sm">Folder Path</Label>
-						<div className="flex gap-2">
-							<Input
-								value={folderPath}
-								onChange={(e) => handleFolderPathChange(e.target.value)}
-								placeholder="/path/to/your/folder"
-								className="border-slate-400/20 focus-visible:border-slate-400/40 font-mono flex-1"
-							/>
-							{isElectron && (
-								<Button type="button" variant="outline" size="sm" onClick={handleBrowse} className="shrink-0">
-									<FolderSync className="h-4 w-4 mr-1" />
-									Browse
-								</Button>
-							)}
-						</div>
-					</div>
-
-					<div className="space-y-2">
-						<Label className="text-xs sm:text-sm">Display Name</Label>
-						<Input
-							value={folderName}
-							onChange={(e) => handleFolderNameChange(e.target.value)}
-							placeholder="My Notes"
-							className="border-slate-400/20 focus-visible:border-slate-400/40"
-						/>
-					</div>
-
-					<div className="space-y-2">
-						<Label className="text-xs sm:text-sm">Exclude Patterns</Label>
-						<Input
-							value={excludePatterns}
-							onChange={(e) => handleExcludePatternsChange(e.target.value)}
-							placeholder="node_modules, .git, .DS_Store"
-							className="border-slate-400/20 focus-visible:border-slate-400/40 font-mono"
-						/>
-						<p className="text-[10px] sm:text-xs text-muted-foreground">
-							Comma-separated patterns of directories/files to exclude.
-						</p>
-					</div>
-
-					<div className="space-y-2">
-						<Label className="text-xs sm:text-sm">File Extensions (optional)</Label>
-						<Input
-							value={fileExtensions}
-							onChange={(e) => handleFileExtensionsChange(e.target.value)}
-							placeholder=".md, .txt, .rst"
-							className="border-slate-400/20 focus-visible:border-slate-400/40 font-mono"
-						/>
-						<p className="text-[10px] sm:text-xs text-muted-foreground">
-							Leave empty to index all supported files.
-						</p>
-					</div>
-				</div>
-			</div>
-		</div>
-	);
-};
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/index.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/index.tsx
index 3dc1891c8..a63435260 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/index.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/index.tsx
@@ -19,7 +19,6 @@ import { JiraConfig } from "./components/jira-config";
 import { LinkupApiConfig } from "./components/linkup-api-config";
 import { LumaConfig } from "./components/luma-config";
 import { MCPConfig } from "./components/mcp-config";
-import { LocalFolderConfig } from "./components/local-folder-config";
 import { ObsidianConfig } from "./components/obsidian-config";
 import { OneDriveConfig } from "./components/onedrive-config";
 import { SlackConfig } from "./components/slack-config";
@@ -83,8 +82,6 @@ export function getConnectorConfigComponent(
 			return MCPConfig;
 		case "OBSIDIAN_CONNECTOR":
 			return ObsidianConfig;
-		case "LOCAL_FOLDER_CONNECTOR":
-			return LocalFolderConfig;
 		case "COMPOSIO_GOOGLE_DRIVE_CONNECTOR":
 			return ComposioDriveConfig;
 		case "COMPOSIO_GMAIL_CONNECTOR":
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-connect-view.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-connect-view.tsx
index 0b6d0917a..596b98e93 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-connect-view.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-connect-view.tsx
@@ -20,7 +20,6 @@ const FORM_ID_MAP: Record<string, string> = {
 	CIRCLEBACK_CONNECTOR: "circleback-connect-form",
 	MCP_CONNECTOR: "mcp-connect-form",
 	OBSIDIAN_CONNECTOR: "obsidian-connect-form",
-	LOCAL_FOLDER_CONNECTOR: "local-folder-connect-form",
 };
 
 interface ConnectorConnectViewProps {
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx
index dcedb4743..05d42adcb 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx
@@ -278,8 +278,7 @@ export const ConnectorEditView: FC<ConnectorEditViewProps> = ({
 									connector.connector_type !== "DROPBOX_CONNECTOR" &&
 									connector.connector_type !== "ONEDRIVE_CONNECTOR" &&
 									connector.connector_type !== "WEBCRAWLER_CONNECTOR" &&
-									connector.connector_type !== "GITHUB_CONNECTOR" &&
-									connector.connector_type !== "LOCAL_FOLDER_CONNECTOR" && (
+									connector.connector_type !== "GITHUB_CONNECTOR" && (
 										<DateRangeSelector
 											startDate={startDate}
 											endDate={endDate}
@@ -294,9 +293,7 @@ export const ConnectorEditView: FC<ConnectorEditViewProps> = ({
 										/>
 									)}
 
-								{/* Periodic sync - shown for all indexable connectors except Local Folder */}
-								{connector.connector_type !== "LOCAL_FOLDER_CONNECTOR" &&
-									(() => {
+								{(() => {
 										const isGoogleDrive = connector.connector_type === "GOOGLE_DRIVE_CONNECTOR";
 										const isComposioGoogleDrive =
 											connector.connector_type === "COMPOSIO_GOOGLE_DRIVE_CONNECTOR";
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/indexing-configuration-view.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/indexing-configuration-view.tsx
index 436ce7843..e583cbe17 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/indexing-configuration-view.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/indexing-configuration-view.tsx
@@ -164,8 +164,7 @@ export const IndexingConfigurationView: FC<IndexingConfigurationViewProps> = ({
 									config.connectorType !== "DROPBOX_CONNECTOR" &&
 									config.connectorType !== "ONEDRIVE_CONNECTOR" &&
 									config.connectorType !== "WEBCRAWLER_CONNECTOR" &&
-									config.connectorType !== "GITHUB_CONNECTOR" &&
-									config.connectorType !== "LOCAL_FOLDER_CONNECTOR" && (
+									config.connectorType !== "GITHUB_CONNECTOR" && (
 										<DateRangeSelector
 											startDate={startDate}
 											endDate={endDate}
@@ -180,12 +179,10 @@ export const IndexingConfigurationView: FC<IndexingConfigurationViewProps> = ({
 										/>
 									)}
 
-								{/* Periodic sync - not shown for file-based connectors (Drive, Dropbox, OneDrive) or Local Folder in initial setup; configured in edit view instead */}
 								{config.connectorType !== "GOOGLE_DRIVE_CONNECTOR" &&
 									config.connectorType !== "COMPOSIO_GOOGLE_DRIVE_CONNECTOR" &&
 									config.connectorType !== "DROPBOX_CONNECTOR" &&
-									config.connectorType !== "ONEDRIVE_CONNECTOR" &&
-									config.connectorType !== "LOCAL_FOLDER_CONNECTOR" && (
+									config.connectorType !== "ONEDRIVE_CONNECTOR" && (
 										<PeriodicSyncConfig
 											enabled={periodicEnabled}
 											frequencyMinutes={frequencyMinutes}

From 5d6e3ffb7b353ee8766fa212d2271a35e7d63455 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 22:20:11 +0530
Subject: [PATCH 24/70] feat: add renderer readiness signaling and update IPC
 channels for folder sync

---
 surfsense_desktop/src/ipc/channels.ts         |  1 +
 surfsense_desktop/src/ipc/handlers.ts         |  5 ++
 .../src/modules/folder-watcher.ts             | 61 +++++++++++++------
 surfsense_desktop/src/preload.ts              |  1 +
 4 files changed, 48 insertions(+), 20 deletions(-)

diff --git a/surfsense_desktop/src/ipc/channels.ts b/surfsense_desktop/src/ipc/channels.ts
index 362d3362d..66788d90e 100644
--- a/surfsense_desktop/src/ipc/channels.ts
+++ b/surfsense_desktop/src/ipc/channels.ts
@@ -16,4 +16,5 @@ export const IPC_CHANNELS = {
   FOLDER_SYNC_WATCHER_READY: 'folder-sync:watcher-ready',
   FOLDER_SYNC_PAUSE: 'folder-sync:pause',
   FOLDER_SYNC_RESUME: 'folder-sync:resume',
+  FOLDER_SYNC_RENDERER_READY: 'folder-sync:renderer-ready',
 } as const;
diff --git a/surfsense_desktop/src/ipc/handlers.ts b/surfsense_desktop/src/ipc/handlers.ts
index 2baf957b0..19051e871 100644
--- a/surfsense_desktop/src/ipc/handlers.ts
+++ b/surfsense_desktop/src/ipc/handlers.ts
@@ -8,6 +8,7 @@ import {
   getWatcherStatus,
   pauseWatcher,
   resumeWatcher,
+  markRendererReady,
 } from '../modules/folder-watcher';
 
 export function registerIpcHandlers(): void {
@@ -44,4 +45,8 @@ export function registerIpcHandlers(): void {
   ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_PAUSE, () => pauseWatcher());
 
   ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_RESUME, () => resumeWatcher());
+
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_RENDERER_READY, () => {
+    markRendererReady();
+  });
 }
diff --git a/surfsense_desktop/src/modules/folder-watcher.ts b/surfsense_desktop/src/modules/folder-watcher.ts
index 072ae7b3f..81a835c22 100644
--- a/surfsense_desktop/src/modules/folder-watcher.ts
+++ b/surfsense_desktop/src/modules/folder-watcher.ts
@@ -9,7 +9,7 @@ export interface WatchedFolderConfig {
   name: string;
   excludePatterns: string[];
   fileExtensions: string[] | null;
-  connectorId: number;
+  rootFolderId: number | null;
   searchSpaceId: number;
   active: boolean;
 }
@@ -34,6 +34,25 @@ let watchers: Map<string, WatcherEntry> = new Map();
  */
 const mtimeMaps: Map<string, MtimeMap> = new Map();
 
+let rendererReady = false;
+const pendingEvents: any[] = [];
+
+export function markRendererReady() {
+  rendererReady = true;
+  for (const event of pendingEvents) {
+    sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, event);
+  }
+  pendingEvents.length = 0;
+}
+
+function sendFileChangedEvent(data: any) {
+  if (rendererReady) {
+    sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, data);
+  } else {
+    pendingEvents.push(data);
+  }
+}
+
 async function getStore() {
   if (!store) {
     const { default: Store } = await import('electron-store');
@@ -83,7 +102,6 @@ function walkFolderMtimes(config: WatchedFolderConfig): MtimeMap {
     for (const entry of entries) {
       const name = entry.name;
 
-      // Skip dotfiles/dotdirs and excluded names
       if (name.startsWith('.') || excludes.has(name)) continue;
 
       const full = path.join(dir, name);
@@ -131,7 +149,6 @@ async function startWatcher(config: WatchedFolderConfig) {
     return;
   }
 
-  // Load persisted mtime map into memory before starting the watcher
   const ms = await getMtimeStore();
   const storedMap: MtimeMap = ms.get(config.path) ?? {};
   mtimeMaps.set(config.path, { ...storedMap });
@@ -156,45 +173,49 @@ async function startWatcher(config: WatchedFolderConfig) {
   watcher.on('ready', () => {
     ready = true;
 
-    // Detect offline changes by diffing current filesystem against stored mtime map
     const currentMap = walkFolderMtimes(config);
     const storedSnapshot = loadMtimeMap(config.path);
     const now = Date.now();
 
+    // Track which files are unchanged so we can selectively update the mtime map
+    const unchangedMap: MtimeMap = {};
+
     for (const [rel, currentMtime] of Object.entries(currentMap)) {
       const storedMtime = storedSnapshot[rel];
       if (storedMtime === undefined) {
-        // New file added while app was closed
-        sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, {
-          connectorId: config.connectorId,
+        sendFileChangedEvent({
+          rootFolderId: config.rootFolderId,
           searchSpaceId: config.searchSpaceId,
           folderPath: config.path,
+          folderName: config.name,
           relativePath: rel,
           fullPath: path.join(config.path, rel),
           action: 'add',
           timestamp: now,
         });
       } else if (Math.abs(currentMtime - storedMtime) >= MTIME_TOLERANCE_S * 1000) {
-        // File modified while app was closed
-        sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, {
-          connectorId: config.connectorId,
+        sendFileChangedEvent({
+          rootFolderId: config.rootFolderId,
           searchSpaceId: config.searchSpaceId,
           folderPath: config.path,
+          folderName: config.name,
           relativePath: rel,
           fullPath: path.join(config.path, rel),
           action: 'change',
           timestamp: now,
         });
+      } else {
+        unchangedMap[rel] = currentMtime;
       }
     }
 
     for (const rel of Object.keys(storedSnapshot)) {
       if (!(rel in currentMap)) {
-        // File deleted while app was closed
-        sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, {
-          connectorId: config.connectorId,
+        sendFileChangedEvent({
+          rootFolderId: config.rootFolderId,
           searchSpaceId: config.searchSpaceId,
           folderPath: config.path,
+          folderName: config.name,
           relativePath: rel,
           fullPath: path.join(config.path, rel),
           action: 'unlink',
@@ -203,12 +224,13 @@ async function startWatcher(config: WatchedFolderConfig) {
       }
     }
 
-    // Replace stored map with current filesystem state
-    mtimeMaps.set(config.path, currentMap);
+    // Only update the mtime map for unchanged files; changed files keep their
+    // stored mtime so they'll be re-detected if the app crashes before indexing.
+    mtimeMaps.set(config.path, unchangedMap);
     persistMtimeMap(config.path);
 
     sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_WATCHER_READY, {
-      connectorId: config.connectorId,
+      rootFolderId: config.rootFolderId,
       folderPath: config.path,
     });
   });
@@ -226,7 +248,6 @@ async function startWatcher(config: WatchedFolderConfig) {
       if (!config.fileExtensions.includes(ext)) return;
     }
 
-    // Keep mtime map in sync with live changes
     const map = mtimeMaps.get(config.path);
     if (map) {
       if (action === 'unlink') {
@@ -241,10 +262,11 @@ async function startWatcher(config: WatchedFolderConfig) {
       persistMtimeMap(config.path);
     }
 
-    sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, {
-      connectorId: config.connectorId,
+    sendFileChangedEvent({
+      rootFolderId: config.rootFolderId,
       searchSpaceId: config.searchSpaceId,
       folderPath: config.path,
+      folderName: config.name,
       relativePath,
       fullPath: filePath,
       action,
@@ -311,7 +333,6 @@ export async function removeWatchedFolder(
 
   stopWatcher(folderPath);
 
-  // Clean up persisted mtime map for this folder
   mtimeMaps.delete(folderPath);
   const ms = await getMtimeStore();
   ms.delete(folderPath);
diff --git a/surfsense_desktop/src/preload.ts b/surfsense_desktop/src/preload.ts
index 8f65aa633..7c190db10 100644
--- a/surfsense_desktop/src/preload.ts
+++ b/surfsense_desktop/src/preload.ts
@@ -44,4 +44,5 @@ contextBridge.exposeInMainWorld('electronAPI', {
   },
   pauseWatcher: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_PAUSE),
   resumeWatcher: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_RESUME),
+  signalRendererReady: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_RENDERER_READY),
 });

From 493d720b891cf6ef478223d2645ba9e4b9504ab6 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 22:21:01 +0530
Subject: [PATCH 25/70] refactor: remove Local Folder connector references and
 enhance folder management features

---
 .../constants/connector-constants.ts          |   8 -
 .../hooks/use-connector-dialog.ts             |  28 ---
 .../utils/connector-document-mapping.ts       |   1 -
 .../components/documents/FolderNode.tsx       | 139 ++++++++-----
 .../components/documents/FolderTreeView.tsx   |   9 +
 .../components/editor-panel/editor-panel.tsx  |  18 +-
 .../layout/ui/sidebar/DocumentsSidebar.tsx    | 186 ++++++++++++++----
 7 files changed, 257 insertions(+), 132 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/connector-popup/constants/connector-constants.ts b/surfsense_web/components/assistant-ui/connector-popup/constants/connector-constants.ts
index 3f7d90cd8..2e92f637b 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/constants/connector-constants.ts
+++ b/surfsense_web/components/assistant-ui/connector-popup/constants/connector-constants.ts
@@ -184,14 +184,6 @@ export const OTHER_CONNECTORS = [
 		connectorType: EnumConnectorName.OBSIDIAN_CONNECTOR,
 		selfHostedOnly: true,
 	},
-	{
-		id: "local-folder-connector",
-		title: "Local Folder",
-		description: "Watch and sync local folders (desktop only)",
-		connectorType: EnumConnectorName.LOCAL_FOLDER_CONNECTOR,
-		selfHostedOnly: true,
-		desktopOnly: true,
-	},
 ] as const;
 
 // Composio Connectors - Individual entries for each supported toolkit
diff --git a/surfsense_web/components/assistant-ui/connector-popup/hooks/use-connector-dialog.ts b/surfsense_web/components/assistant-ui/connector-popup/hooks/use-connector-dialog.ts
index 2404b8eb5..6543bbd72 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/hooks/use-connector-dialog.ts
+++ b/surfsense_web/components/assistant-ui/connector-popup/hooks/use-connector-dialog.ts
@@ -586,23 +586,6 @@ export const useConnectorDialog = () => {
 									},
 								});
 
-								// Register folder watcher in Electron for real-time sync
-								if (
-									currentConnectorType === EnumConnectorName.LOCAL_FOLDER_CONNECTOR &&
-									window.electronAPI?.addWatchedFolder
-								) {
-									const cfg = connector.config || {};
-									await window.electronAPI.addWatchedFolder({
-										path: cfg.folder_path as string,
-										name: cfg.folder_name as string,
-										excludePatterns: (cfg.exclude_patterns as string[]) || [],
-										fileExtensions: (cfg.file_extensions as string[] | null) ?? null,
-										connectorId: connector.id,
-										searchSpaceId: Number(searchSpaceId),
-										active: true,
-									});
-								}
-
 								const successMessage =
 									currentConnectorType === "MCP_CONNECTOR"
 										? `${connector.name} added successfully`
@@ -1207,17 +1190,6 @@ export const useConnectorDialog = () => {
 					id: editingConnector.id,
 				});
 
-				// Unregister folder watcher in Electron when removing a Local Folder connector
-				if (
-					editingConnector.connector_type === EnumConnectorName.LOCAL_FOLDER_CONNECTOR &&
-					window.electronAPI?.removeWatchedFolder &&
-					editingConnector.config?.folder_path
-				) {
-					await window.electronAPI.removeWatchedFolder(
-						editingConnector.config.folder_path as string
-					);
-				}
-
 				// Track connector deleted event
 				trackConnectorDeleted(
 					Number(searchSpaceId),
diff --git a/surfsense_web/components/assistant-ui/connector-popup/utils/connector-document-mapping.ts b/surfsense_web/components/assistant-ui/connector-popup/utils/connector-document-mapping.ts
index dd5978002..f924bb15f 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/utils/connector-document-mapping.ts
+++ b/surfsense_web/components/assistant-ui/connector-popup/utils/connector-document-mapping.ts
@@ -29,7 +29,6 @@ export const CONNECTOR_TO_DOCUMENT_TYPE: Record<string, string> = {
 	BOOKSTACK_CONNECTOR: "BOOKSTACK_CONNECTOR",
 	CIRCLEBACK_CONNECTOR: "CIRCLEBACK",
 	OBSIDIAN_CONNECTOR: "OBSIDIAN_CONNECTOR",
-	LOCAL_FOLDER_CONNECTOR: "LOCAL_FOLDER_FILE",
 
 	// Special mappings (connector type differs from document type)
 	GOOGLE_DRIVE_CONNECTOR: "GOOGLE_DRIVE_FILE",
diff --git a/surfsense_web/components/documents/FolderNode.tsx b/surfsense_web/components/documents/FolderNode.tsx
index 6a36f724f..1521c06fe 100644
--- a/surfsense_web/components/documents/FolderNode.tsx
+++ b/surfsense_web/components/documents/FolderNode.tsx
@@ -3,12 +3,15 @@
 import {
 	ChevronDown,
 	ChevronRight,
+	Eye,
+	EyeOff,
 	Folder,
 	FolderOpen,
 	FolderPlus,
 	MoreHorizontal,
 	Move,
 	PenLine,
+	RefreshCw,
 	Trash2,
 } from "lucide-react";
 import React, { useCallback, useEffect, useRef, useState } from "react";
@@ -70,6 +73,9 @@ interface FolderNodeProps {
 	disabledDropIds?: Set<number>;
 	contextMenuOpen?: boolean;
 	onContextMenuOpenChange?: (open: boolean) => void;
+	isWatched?: boolean;
+	onRescan?: (folder: FolderDisplay) => void;
+	onStopWatching?: (folder: FolderDisplay) => void;
 }
 
 function getDropZone(
@@ -107,6 +113,9 @@ export const FolderNode = React.memo(function FolderNode({
 	disabledDropIds,
 	contextMenuOpen,
 	onContextMenuOpenChange,
+	isWatched,
+	onRescan,
+	onStopWatching,
 }: FolderNodeProps) {
 	const [renameValue, setRenameValue] = useState(folder.name);
 	const inputRef = useRef<HTMLInputElement>(null);
@@ -307,73 +316,107 @@ export const FolderNode = React.memo(function FolderNode({
 									<MoreHorizontal className="h-3.5 w-3.5" />
 								</Button>
 							</DropdownMenuTrigger>
-							<DropdownMenuContent align="end" className="w-40">
+						<DropdownMenuContent align="end" className="w-40">
+							{isWatched && onRescan && (
 								<DropdownMenuItem
 									onClick={(e) => {
 										e.stopPropagation();
-										onCreateSubfolder(folder.id);
+										onRescan(folder);
 									}}
 								>
-									<FolderPlus className="mr-2 h-4 w-4" />
-									New subfolder
+									<RefreshCw className="mr-2 h-4 w-4" />
+									Re-scan
 								</DropdownMenuItem>
+							)}
+							{isWatched && onStopWatching && (
 								<DropdownMenuItem
 									onClick={(e) => {
 										e.stopPropagation();
-										startRename();
+										onStopWatching(folder);
 									}}
 								>
-									<PenLine className="mr-2 h-4 w-4" />
-									Rename
+									<EyeOff className="mr-2 h-4 w-4" />
+									Stop watching
 								</DropdownMenuItem>
-								<DropdownMenuItem
-									onClick={(e) => {
-										e.stopPropagation();
-										onMove(folder);
-									}}
-								>
-									<Move className="mr-2 h-4 w-4" />
-									Move to...
-								</DropdownMenuItem>
-								<DropdownMenuItem
-									className="text-destructive focus:text-destructive"
-									onClick={(e) => {
-										e.stopPropagation();
-										onDelete(folder);
-									}}
-								>
-									<Trash2 className="mr-2 h-4 w-4" />
-									Delete
-								</DropdownMenuItem>
-							</DropdownMenuContent>
+							)}
+							<DropdownMenuItem
+								onClick={(e) => {
+									e.stopPropagation();
+									onCreateSubfolder(folder.id);
+								}}
+							>
+								<FolderPlus className="mr-2 h-4 w-4" />
+								New subfolder
+							</DropdownMenuItem>
+							<DropdownMenuItem
+								onClick={(e) => {
+									e.stopPropagation();
+									startRename();
+								}}
+							>
+								<PenLine className="mr-2 h-4 w-4" />
+								Rename
+							</DropdownMenuItem>
+							<DropdownMenuItem
+								onClick={(e) => {
+									e.stopPropagation();
+									onMove(folder);
+								}}
+							>
+								<Move className="mr-2 h-4 w-4" />
+								Move to...
+							</DropdownMenuItem>
+							<DropdownMenuItem
+								className="text-destructive focus:text-destructive"
+								onClick={(e) => {
+									e.stopPropagation();
+									onDelete(folder);
+								}}
+							>
+								<Trash2 className="mr-2 h-4 w-4" />
+								Delete
+							</DropdownMenuItem>
+						</DropdownMenuContent>
 						</DropdownMenu>
 					)}
 				</div>
 			</ContextMenuTrigger>
 
-			{!isRenaming && contextMenuOpen && (
-				<ContextMenuContent className="w-40">
-					<ContextMenuItem onClick={() => onCreateSubfolder(folder.id)}>
-						<FolderPlus className="mr-2 h-4 w-4" />
-						New subfolder
+		{!isRenaming && contextMenuOpen && (
+			<ContextMenuContent className="w-40">
+				{isWatched && onRescan && (
+					<ContextMenuItem onClick={() => onRescan(folder)}>
+						<RefreshCw className="mr-2 h-4 w-4" />
+						Re-scan
 					</ContextMenuItem>
-					<ContextMenuItem onClick={() => startRename()}>
-						<PenLine className="mr-2 h-4 w-4" />
-						Rename
+				)}
+				{isWatched && onStopWatching && (
+					<ContextMenuItem onClick={() => onStopWatching(folder)}>
+						<EyeOff className="mr-2 h-4 w-4" />
+						Stop watching
 					</ContextMenuItem>
-					<ContextMenuItem onClick={() => onMove(folder)}>
-						<Move className="mr-2 h-4 w-4" />
-						Move to...
-					</ContextMenuItem>
-					<ContextMenuItem
-						className="text-destructive focus:text-destructive"
-						onClick={() => onDelete(folder)}
-					>
-						<Trash2 className="mr-2 h-4 w-4" />
-						Delete
-					</ContextMenuItem>
-				</ContextMenuContent>
-			)}
+				)}
+				<ContextMenuItem onClick={() => onCreateSubfolder(folder.id)}>
+					<FolderPlus className="mr-2 h-4 w-4" />
+					New subfolder
+				</ContextMenuItem>
+				<ContextMenuItem onClick={() => startRename()}>
+					<PenLine className="mr-2 h-4 w-4" />
+					Rename
+				</ContextMenuItem>
+				<ContextMenuItem onClick={() => onMove(folder)}>
+					<Move className="mr-2 h-4 w-4" />
+					Move to...
+				</ContextMenuItem>
+				<ContextMenuItem
+					className="text-destructive focus:text-destructive"
+					onClick={() => onDelete(folder)}
+				>
+					<Trash2 className="mr-2 h-4 w-4" />
+					Delete
+				</ContextMenuItem>
+			</ContextMenuContent>
+		)}
 		</ContextMenu>
 	);
 });
diff --git a/surfsense_web/components/documents/FolderTreeView.tsx b/surfsense_web/components/documents/FolderTreeView.tsx
index 7695923e3..5945edccb 100644
--- a/surfsense_web/components/documents/FolderTreeView.tsx
+++ b/surfsense_web/components/documents/FolderTreeView.tsx
@@ -40,6 +40,9 @@ interface FolderTreeViewProps {
 		targetFolderId: number | null
 	) => void;
 	onReorderFolder?: (folderId: number, beforePos: string | null, afterPos: string | null) => void;
+	watchedFolderIds?: Set<number>;
+	onRescanFolder?: (folder: FolderDisplay) => void;
+	onStopWatchingFolder?: (folder: FolderDisplay) => void;
 }
 
 function groupBy<T>(items: T[], keyFn: (item: T) => string | number): Record<string | number, T[]> {
@@ -73,6 +76,9 @@ export function FolderTreeView({
 	searchQuery,
 	onDropIntoFolder,
 	onReorderFolder,
+	watchedFolderIds,
+	onRescanFolder,
+	onStopWatchingFolder,
 }: FolderTreeViewProps) {
 	const foldersByParent = useMemo(() => groupBy(folders, (f) => f.parentId ?? "root"), [folders]);
 
@@ -204,6 +210,9 @@ export function FolderTreeView({
 					siblingPositions={siblingPositions}
 					contextMenuOpen={openContextMenuId === `folder-${f.id}`}
 					onContextMenuOpenChange={(open) => setOpenContextMenuId(open ? `folder-${f.id}` : null)}
+					isWatched={watchedFolderIds?.has(f.id)}
+					onRescan={onRescanFolder}
+					onStopWatching={onStopWatchingFolder}
 				/>
 			);
 
diff --git a/surfsense_web/components/editor-panel/editor-panel.tsx b/surfsense_web/components/editor-panel/editor-panel.tsx
index 802a5ffc3..a1195ef33 100644
--- a/surfsense_web/components/editor-panel/editor-panel.tsx
+++ b/surfsense_web/components/editor-panel/editor-panel.tsx
@@ -6,6 +6,7 @@ import dynamic from "next/dynamic";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { toast } from "sonner";
 import { closeEditorPanelAtom, editorPanelAtom } from "@/atoms/editor/editor-panel.atom";
+import { VersionHistoryButton } from "@/components/documents/version-history";
 import { MarkdownViewer } from "@/components/markdown-viewer";
 import { Button } from "@/components/ui/button";
 import { Drawer, DrawerContent, DrawerHandle, DrawerTitle } from "@/components/ui/drawer";
@@ -180,12 +181,16 @@ export function EditorPanelContent({
 	return (
 		<>
 			<div className="flex items-center justify-between px-4 py-2 shrink-0 border-b">
-				<div className="flex-1 min-w-0">
-					<h2 className="text-sm font-semibold truncate">{displayTitle}</h2>
-					{isEditableType && editedMarkdown !== null && (
-						<p className="text-[10px] text-muted-foreground">Unsaved changes</p>
-					)}
-				</div>
+			<div className="flex-1 min-w-0">
+				<h2 className="text-sm font-semibold truncate">{displayTitle}</h2>
+				{isEditableType && editedMarkdown !== null && (
+					<p className="text-[10px] text-muted-foreground">Unsaved changes</p>
+				)}
+			</div>
+			<div className="flex items-center gap-1 shrink-0">
+				{editorDoc?.document_type && (
+					<VersionHistoryButton documentId={documentId} documentType={editorDoc.document_type} />
+				)}
 				{onClose && (
 					<Button variant="ghost" size="icon" onClick={onClose} className="size-7 shrink-0">
 						<XIcon className="size-4" />
@@ -193,6 +198,7 @@ export function EditorPanelContent({
 					</Button>
 				)}
 			</div>
+		</div>
 
 			<div className="flex-1 overflow-hidden">
 				{isLoading ? (
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index d880524bd..202d170d9 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -40,6 +40,7 @@ import { getConnectorIcon } from "@/contracts/enums/connectorIcons";
 import type { DocumentTypeEnum } from "@/contracts/types/document.types";
 import { useDebouncedValue } from "@/hooks/use-debounced-value";
 import { useMediaQuery } from "@/hooks/use-media-query";
+import { documentsApiService } from "@/lib/apis/documents-api.service";
 import { foldersApiService } from "@/lib/apis/folders-api.service";
 import { authenticatedFetch } from "@/lib/auth-utils";
 import { queries } from "@/zero/queries/index";
@@ -92,6 +93,24 @@ export function DocumentsSidebar({
 	const [search, setSearch] = useState("");
 	const debouncedSearch = useDebouncedValue(search, 250);
 	const [activeTypes, setActiveTypes] = useState<DocumentTypeEnum[]>([]);
+	const [watchedFolderIds, setWatchedFolderIds] = useState<Set<number>>(new Set());
+
+	useEffect(() => {
+		const api = typeof window !== "undefined" ? window.electronAPI : null;
+		if (!api?.getWatchedFolders) return;
+
+		async function loadWatchedIds() {
+			const folders = await api!.getWatchedFolders();
+			const ids = new Set(
+				folders
+					.filter((f) => f.rootFolderId != null)
+					.map((f) => f.rootFolderId as number)
+			);
+			setWatchedFolderIds(ids);
+		}
+
+		loadWatchedIds();
+	}, []);
 	const { mutateAsync: deleteDocumentMutation } = useAtomValue(deleteDocumentMutationAtom);
 
 	const [sidebarDocs, setSidebarDocs] = useAtom(sidebarSelectedDocumentsAtom);
@@ -223,6 +242,87 @@ export function DocumentsSidebar({
 		[createFolderParentId, searchSpaceId, setExpandedFolderMap]
 	);
 
+	const isElectron = typeof window !== "undefined" && !!window.electronAPI;
+
+	const handleWatchFolder = useCallback(async () => {
+		const api = window.electronAPI;
+		if (!api) return;
+
+		const folderPath = await api.selectFolder();
+		if (!folderPath) return;
+
+		const folderName = folderPath.split("/").pop() || folderPath.split("\\").pop() || folderPath;
+
+		try {
+			const result = await documentsApiService.folderIndex(searchSpaceId, {
+				folder_path: folderPath,
+				folder_name: folderName,
+				search_space_id: searchSpaceId,
+			});
+
+			const rootFolderId = (result as { root_folder_id?: number })?.root_folder_id ?? null;
+
+			await api.addWatchedFolder({
+				path: folderPath,
+				name: folderName,
+				excludePatterns: [".git", "node_modules", "__pycache__", ".DS_Store", ".obsidian", ".trash"],
+				fileExtensions: null,
+				rootFolderId,
+				searchSpaceId,
+				active: true,
+			});
+
+			toast.success(`Watching folder: ${folderName}`);
+		} catch (err) {
+			toast.error((err as Error)?.message || "Failed to watch folder");
+		}
+	}, [searchSpaceId]);
+
+	const handleRescanFolder = useCallback(
+		async (folder: FolderDisplay) => {
+			const api = window.electronAPI;
+			if (!api) return;
+
+			const watchedFolders = await api.getWatchedFolders();
+			const matched = watchedFolders.find((wf) => wf.rootFolderId === folder.id);
+			if (!matched) {
+				toast.error("This folder is not being watched");
+				return;
+			}
+
+			try {
+				await documentsApiService.folderIndex(searchSpaceId, {
+					folder_path: matched.path,
+					folder_name: matched.name,
+					search_space_id: searchSpaceId,
+					root_folder_id: folder.id,
+				});
+				toast.success(`Re-scanning folder: ${matched.name}`);
+			} catch (err) {
+				toast.error((err as Error)?.message || "Failed to re-scan folder");
+			}
+		},
+		[searchSpaceId]
+	);
+
+	const handleStopWatching = useCallback(
+		async (folder: FolderDisplay) => {
+			const api = window.electronAPI;
+			if (!api) return;
+
+			const watchedFolders = await api.getWatchedFolders();
+			const matched = watchedFolders.find((wf) => wf.rootFolderId === folder.id);
+			if (!matched) {
+				toast.error("This folder is not being watched");
+				return;
+			}
+
+			await api.removeWatchedFolder(matched.path);
+			toast.success(`Stopped watching: ${matched.name}`);
+		},
+		[]
+	);
+
 	const handleRenameFolder = useCallback(async (folder: FolderDisplay, newName: string) => {
 		try {
 			await foldersApiService.updateFolder(folder.id, { name: newName });
@@ -641,14 +741,15 @@ export function DocumentsSidebar({
 
 			<div className="flex-1 min-h-0 overflow-x-hidden pt-0 flex flex-col">
 				<div className="px-4 pb-2">
-					<DocumentsFilters
-						typeCounts={typeCounts}
-						onSearch={setSearch}
-						searchValue={search}
-						onToggleType={onToggleType}
-						activeTypes={activeTypes}
-						onCreateFolder={() => handleCreateFolder(null)}
-					/>
+				<DocumentsFilters
+					typeCounts={typeCounts}
+					onSearch={setSearch}
+					searchValue={search}
+					onToggleType={onToggleType}
+					activeTypes={activeTypes}
+					onCreateFolder={() => handleCreateFolder(null)}
+					onWatchFolder={isElectron ? handleWatchFolder : undefined}
+				/>
 				</div>
 
 				{deletableSelectedIds.length > 0 && (
@@ -666,39 +767,42 @@ export function DocumentsSidebar({
 				)}
 
 				<FolderTreeView
-					folders={treeFolders}
-					documents={searchFilteredDocuments}
-					expandedIds={expandedIds}
-					onToggleExpand={toggleFolderExpand}
-					mentionedDocIds={mentionedDocIds}
-					onToggleChatMention={handleToggleChatMention}
-					onToggleFolderSelect={handleToggleFolderSelect}
-					onRenameFolder={handleRenameFolder}
-					onDeleteFolder={handleDeleteFolder}
-					onMoveFolder={handleMoveFolder}
-					onCreateFolder={handleCreateFolder}
-					searchQuery={debouncedSearch.trim() || undefined}
-					onPreviewDocument={(doc) => {
-						openEditorPanel({
-							documentId: doc.id,
-							searchSpaceId,
-							title: doc.title,
-						});
-					}}
-					onEditDocument={(doc) => {
-						openEditorPanel({
-							documentId: doc.id,
-							searchSpaceId,
-							title: doc.title,
-						});
-					}}
-					onDeleteDocument={(doc) => handleDeleteDocument(doc.id)}
-					onMoveDocument={handleMoveDocument}
-					onExportDocument={handleExportDocument}
-					activeTypes={activeTypes}
-					onDropIntoFolder={handleDropIntoFolder}
-					onReorderFolder={handleReorderFolder}
-				/>
+				folders={treeFolders}
+				documents={searchFilteredDocuments}
+				expandedIds={expandedIds}
+				onToggleExpand={toggleFolderExpand}
+				mentionedDocIds={mentionedDocIds}
+				onToggleChatMention={handleToggleChatMention}
+				onToggleFolderSelect={handleToggleFolderSelect}
+				onRenameFolder={handleRenameFolder}
+				onDeleteFolder={handleDeleteFolder}
+				onMoveFolder={handleMoveFolder}
+				onCreateFolder={handleCreateFolder}
+				searchQuery={debouncedSearch.trim() || undefined}
+				onPreviewDocument={(doc) => {
+					openEditorPanel({
+						documentId: doc.id,
+						searchSpaceId,
+						title: doc.title,
+					});
+				}}
+				onEditDocument={(doc) => {
+					openEditorPanel({
+						documentId: doc.id,
+						searchSpaceId,
+						title: doc.title,
+					});
+				}}
+				onDeleteDocument={(doc) => handleDeleteDocument(doc.id)}
+				onMoveDocument={handleMoveDocument}
+				onExportDocument={handleExportDocument}
+				activeTypes={activeTypes}
+				onDropIntoFolder={handleDropIntoFolder}
+				onReorderFolder={handleReorderFolder}
+				watchedFolderIds={watchedFolderIds}
+				onRescanFolder={handleRescanFolder}
+				onStopWatchingFolder={handleStopWatching}
+			/>
 			</div>
 
 			<FolderPickerDialog

From 149ccb97ddce4a56b15f1cdfce315833edf7a6c5 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 22:21:16 +0530
Subject: [PATCH 26/70] refactor: completely remove Local Folder connector
 references and update folder sync logic

---
 surfsense_web/contracts/enums/connector.ts    |  1 -
 .../contracts/enums/connectorIcons.tsx        |  3 -
 .../contracts/types/connector.types.ts        |  1 -
 surfsense_web/hooks/use-folder-sync.ts        | 62 ++++++++++++++-----
 .../lib/apis/connectors-api.service.ts        | 11 ----
 .../lib/apis/documents-api.service.ts         |  8 +++
 surfsense_web/lib/connectors/utils.ts         |  1 -
 surfsense_web/types/window.d.ts               |  8 ++-
 8 files changed, 60 insertions(+), 35 deletions(-)

diff --git a/surfsense_web/contracts/enums/connector.ts b/surfsense_web/contracts/enums/connector.ts
index ecf96d88e..501f5d9a3 100644
--- a/surfsense_web/contracts/enums/connector.ts
+++ b/surfsense_web/contracts/enums/connector.ts
@@ -25,7 +25,6 @@ export enum EnumConnectorName {
 	YOUTUBE_CONNECTOR = "YOUTUBE_CONNECTOR",
 	CIRCLEBACK_CONNECTOR = "CIRCLEBACK_CONNECTOR",
 	OBSIDIAN_CONNECTOR = "OBSIDIAN_CONNECTOR",
-	LOCAL_FOLDER_CONNECTOR = "LOCAL_FOLDER_CONNECTOR",
 	DROPBOX_CONNECTOR = "DROPBOX_CONNECTOR",
 	MCP_CONNECTOR = "MCP_CONNECTOR",
 	COMPOSIO_GOOGLE_DRIVE_CONNECTOR = "COMPOSIO_GOOGLE_DRIVE_CONNECTOR",
diff --git a/surfsense_web/contracts/enums/connectorIcons.tsx b/surfsense_web/contracts/enums/connectorIcons.tsx
index f7378b74b..2e609b060 100644
--- a/surfsense_web/contracts/enums/connectorIcons.tsx
+++ b/surfsense_web/contracts/enums/connectorIcons.tsx
@@ -3,7 +3,6 @@ import {
 	BookOpen,
 	File,
 	FileText,
-	FolderSync,
 	Globe,
 	Microscope,
 	Search,
@@ -76,8 +75,6 @@ export const getConnectorIcon = (connectorType: EnumConnectorName | string, clas
 			return <Image src="/connectors/circleback.svg" alt="Circleback" {...imgProps} />;
 		case EnumConnectorName.MCP_CONNECTOR:
 			return <Image src="/connectors/modelcontextprotocol.svg" alt="MCP" {...imgProps} />;
-		case EnumConnectorName.LOCAL_FOLDER_CONNECTOR:
-			return <FolderSync {...iconProps} />;
 		case EnumConnectorName.OBSIDIAN_CONNECTOR:
 			return <Image src="/connectors/obsidian.svg" alt="Obsidian" {...imgProps} />;
 		case EnumConnectorName.COMPOSIO_GOOGLE_DRIVE_CONNECTOR:
diff --git a/surfsense_web/contracts/types/connector.types.ts b/surfsense_web/contracts/types/connector.types.ts
index 269941375..b83e05dcc 100644
--- a/surfsense_web/contracts/types/connector.types.ts
+++ b/surfsense_web/contracts/types/connector.types.ts
@@ -30,7 +30,6 @@ export const searchSourceConnectorTypeEnum = z.enum([
 	"DROPBOX_CONNECTOR",
 	"MCP_CONNECTOR",
 	"OBSIDIAN_CONNECTOR",
-	"LOCAL_FOLDER_CONNECTOR",
 	"COMPOSIO_GOOGLE_DRIVE_CONNECTOR",
 	"COMPOSIO_GMAIL_CONNECTOR",
 	"COMPOSIO_GOOGLE_CALENDAR_CONNECTOR",
diff --git a/surfsense_web/hooks/use-folder-sync.ts b/surfsense_web/hooks/use-folder-sync.ts
index a35faf98f..fcfb2814e 100644
--- a/surfsense_web/hooks/use-folder-sync.ts
+++ b/surfsense_web/hooks/use-folder-sync.ts
@@ -1,41 +1,73 @@
 "use client";
 
 import { useEffect, useRef } from "react";
-import { connectorsApiService } from "@/lib/apis/connectors-api.service";
+import { documentsApiService } from "@/lib/apis/documents-api.service";
+
+interface FileChangedEvent {
+	rootFolderId: number | null;
+	searchSpaceId: number;
+	folderPath: string;
+	folderName: string;
+	relativePath: string;
+	fullPath: string;
+	action: string;
+	timestamp: number;
+}
 
 const DEBOUNCE_MS = 2000;
 
 export function useFolderSync() {
-	const pendingRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+	const queueRef = useRef<FileChangedEvent[]>([]);
+	const processingRef = useRef(false);
+	const debounceTimers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+
+	async function processQueue() {
+		if (processingRef.current) return;
+		processingRef.current = true;
+		while (queueRef.current.length > 0) {
+			const event = queueRef.current.shift()!;
+			try {
+				await documentsApiService.folderIndexFile(event.searchSpaceId, {
+					folder_path: event.folderPath,
+					folder_name: event.folderName,
+					search_space_id: event.searchSpaceId,
+					target_file_path: event.fullPath,
+				});
+			} catch (err) {
+				console.error("[FolderSync] Failed to trigger re-index:", err);
+			}
+		}
+		processingRef.current = false;
+	}
 
 	useEffect(() => {
 		const api = typeof window !== "undefined" ? window.electronAPI : null;
 		if (!api?.onFileChanged) return;
 
-		const cleanup = api.onFileChanged((event) => {
-			const key = `${event.connectorId}:${event.fullPath}`;
+		// Signal to main process that the renderer is ready to receive events
+		api.signalRendererReady?.();
 
-			const existing = pendingRef.current.get(key);
+		const cleanup = api.onFileChanged((event: FileChangedEvent) => {
+			const key = `${event.folderPath}:${event.fullPath}`;
+
+			const existing = debounceTimers.current.get(key);
 			if (existing) clearTimeout(existing);
 
-			const timeout = setTimeout(async () => {
-				pendingRef.current.delete(key);
-				try {
-					await connectorsApiService.indexFile(event.connectorId, event.fullPath);
-				} catch (err) {
-					console.error("[FolderSync] Failed to trigger re-index:", err);
-				}
+			const timeout = setTimeout(() => {
+				debounceTimers.current.delete(key);
+				queueRef.current.push(event);
+				processQueue();
 			}, DEBOUNCE_MS);
 
-			pendingRef.current.set(key, timeout);
+			debounceTimers.current.set(key, timeout);
 		});
 
 		return () => {
 			cleanup();
-			for (const timeout of pendingRef.current.values()) {
+			for (const timeout of debounceTimers.current.values()) {
 				clearTimeout(timeout);
 			}
-			pendingRef.current.clear();
+			debounceTimers.current.clear();
 		};
 	}, []);
 }
diff --git a/surfsense_web/lib/apis/connectors-api.service.ts b/surfsense_web/lib/apis/connectors-api.service.ts
index f2722df70..7b94b3746 100644
--- a/surfsense_web/lib/apis/connectors-api.service.ts
+++ b/surfsense_web/lib/apis/connectors-api.service.ts
@@ -405,17 +405,6 @@ class ConnectorsApiService {
 		);
 	};
 
-	// =============================================================================
-	// Local Folder Connector Methods
-	// =============================================================================
-
-	indexFile = async (connectorId: number, filePath: string) => {
-		return baseApiService.post(
-			`/api/v1/search-source-connectors/${connectorId}/index-file`,
-			undefined,
-			{ body: { file_path: filePath } }
-		);
-	};
 }
 
 export type { SlackChannel, DiscordChannel };
diff --git a/surfsense_web/lib/apis/documents-api.service.ts b/surfsense_web/lib/apis/documents-api.service.ts
index d4a80f8a0..c77cd6848 100644
--- a/surfsense_web/lib/apis/documents-api.service.ts
+++ b/surfsense_web/lib/apis/documents-api.service.ts
@@ -395,6 +395,14 @@ class DocumentsApiService {
 		);
 	};
 
+	folderIndex = async (searchSpaceId: number, body: { folder_path: string; folder_name: string; search_space_id: number; exclude_patterns?: string[]; file_extensions?: string[]; root_folder_id?: number; enable_summary?: boolean }) => {
+		return baseApiService.post(`/api/v1/documents/folder-index`, undefined, { body });
+	};
+
+	folderIndexFile = async (searchSpaceId: number, body: { folder_path: string; folder_name: string; search_space_id: number; target_file_path: string; enable_summary?: boolean }) => {
+		return baseApiService.post(`/api/v1/documents/folder-index-file`, undefined, { body });
+	};
+
 	/**
 	 * Delete a document
 	 */
diff --git a/surfsense_web/lib/connectors/utils.ts b/surfsense_web/lib/connectors/utils.ts
index 6ce78be67..90f7f5d21 100644
--- a/surfsense_web/lib/connectors/utils.ts
+++ b/surfsense_web/lib/connectors/utils.ts
@@ -30,7 +30,6 @@ export const getConnectorTypeDisplay = (type: string): string => {
 		YOUTUBE_CONNECTOR: "YouTube",
 		CIRCLEBACK_CONNECTOR: "Circleback",
 		OBSIDIAN_CONNECTOR: "Obsidian",
-		LOCAL_FOLDER_CONNECTOR: "Local Folder",
 		DROPBOX_CONNECTOR: "Dropbox",
 		MCP_CONNECTOR: "MCP Server",
 	};
diff --git a/surfsense_web/types/window.d.ts b/surfsense_web/types/window.d.ts
index 921449b41..b399664d6 100644
--- a/surfsense_web/types/window.d.ts
+++ b/surfsense_web/types/window.d.ts
@@ -5,15 +5,16 @@ interface WatchedFolderConfig {
 	name: string;
 	excludePatterns: string[];
 	fileExtensions: string[] | null;
-	connectorId: number;
+	rootFolderId: number | null;
 	searchSpaceId: number;
 	active: boolean;
 }
 
 interface FolderSyncFileChangedEvent {
-	connectorId: number;
+	rootFolderId: number | null;
 	searchSpaceId: number;
 	folderPath: string;
+	folderName: string;
 	relativePath: string;
 	fullPath: string;
 	action: "add" | "change" | "unlink";
@@ -21,7 +22,7 @@ interface FolderSyncFileChangedEvent {
 }
 
 interface FolderSyncWatcherReadyEvent {
-	connectorId: number;
+	rootFolderId: number | null;
 	folderPath: string;
 }
 
@@ -49,6 +50,7 @@ interface ElectronAPI {
 	onWatcherReady: (callback: (data: FolderSyncWatcherReadyEvent) => void) => () => void;
 	pauseWatcher: () => Promise<void>;
 	resumeWatcher: () => Promise<void>;
+	signalRendererReady: () => Promise<void>;
 }
 
 declare global {

From 22ee5c99cc9a656a3c5f0afae9c100874144e1b6 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 22:21:31 +0530
Subject: [PATCH 27/70] refactor: remove Local Folder connector and related
 tasks, implement new folder indexing endpoints

---
 surfsense_backend/app/db.py                   |   1 -
 .../app/routes/documents_routes.py            | 143 ++++++++++++++++
 .../routes/search_source_connectors_routes.py | 144 ----------------
 .../app/tasks/celery_tasks/connector_tasks.py |  46 ------
 .../app/tasks/celery_tasks/document_tasks.py  |  66 ++++++++
 .../app/tasks/connector_indexers/__init__.py  |   2 -
 .../local_folder_indexer.py                   | 155 ++++++------------
 .../tests/integration/conftest.py             |  19 ---
 .../test_local_folder_pipeline.py             | 126 +++++++-------
 9 files changed, 326 insertions(+), 376 deletions(-)

diff --git a/surfsense_backend/app/db.py b/surfsense_backend/app/db.py
index 25045e84a..1a4d3ea06 100644
--- a/surfsense_backend/app/db.py
+++ b/surfsense_backend/app/db.py
@@ -110,7 +110,6 @@ class SearchSourceConnectorType(StrEnum):
     COMPOSIO_GOOGLE_DRIVE_CONNECTOR = "COMPOSIO_GOOGLE_DRIVE_CONNECTOR"
     COMPOSIO_GMAIL_CONNECTOR = "COMPOSIO_GMAIL_CONNECTOR"
     COMPOSIO_GOOGLE_CALENDAR_CONNECTOR = "COMPOSIO_GOOGLE_CALENDAR_CONNECTOR"
-    LOCAL_FOLDER_CONNECTOR = "LOCAL_FOLDER_CONNECTOR"
 
 
 class PodcastStatus(StrEnum):
diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index 2d999eae3..d7974f9ff 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -2,6 +2,7 @@
 import asyncio
 
 from fastapi import APIRouter, Depends, Form, HTTPException, UploadFile
+from pydantic import BaseModel as PydanticBaseModel
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.future import select
 from sqlalchemy.orm import selectinload
@@ -11,6 +12,7 @@ from app.db import (
     Document,
     DocumentType,
     DocumentVersion,
+    Folder,
     Permission,
     SearchSpace,
     SearchSpaceMembership,
@@ -1258,3 +1260,144 @@ async def restore_document_version(
         "document_id": document_id,
         "restored_version": version_number,
     }
+
+
+# ===== Local folder indexing endpoints =====
+
+
+class FolderIndexRequest(PydanticBaseModel):
+    folder_path: str
+    folder_name: str
+    search_space_id: int
+    exclude_patterns: list[str] | None = None
+    file_extensions: list[str] | None = None
+    root_folder_id: int | None = None
+    enable_summary: bool = False
+
+
+class FolderIndexFileRequest(PydanticBaseModel):
+    folder_path: str
+    folder_name: str
+    search_space_id: int
+    target_file_path: str
+    enable_summary: bool = False
+
+
+@router.post("/documents/folder-index")
+async def folder_index(
+    request: FolderIndexRequest,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Full-scan index of a local folder. Creates the root Folder row synchronously
+    and dispatches the heavy indexing work to a Celery task.
+    Returns the root_folder_id so the desktop can persist it.
+    """
+    from app.config import config as app_config
+
+    if not app_config.is_self_hosted():
+        raise HTTPException(
+            status_code=400,
+            detail="Local folder indexing is only available in self-hosted mode",
+        )
+
+    await check_permission(
+        session,
+        user,
+        request.search_space_id,
+        Permission.DOCUMENTS_CREATE.value,
+        "You don't have permission to create documents in this search space",
+    )
+
+    root_folder_id = request.root_folder_id
+    if root_folder_id:
+        existing = (
+            await session.execute(
+                select(Folder).where(Folder.id == root_folder_id)
+            )
+        ).scalar_one_or_none()
+        if not existing:
+            root_folder_id = None
+
+    if not root_folder_id:
+        root_folder = Folder(
+            name=request.folder_name,
+            search_space_id=request.search_space_id,
+            created_by_id=str(user.id),
+            position="a0",
+        )
+        session.add(root_folder)
+        await session.flush()
+        root_folder_id = root_folder.id
+        await session.commit()
+
+    from app.tasks.celery_tasks.document_tasks import index_local_folder_task
+
+    index_local_folder_task.delay(
+        search_space_id=request.search_space_id,
+        user_id=str(user.id),
+        folder_path=request.folder_path,
+        folder_name=request.folder_name,
+        exclude_patterns=request.exclude_patterns,
+        file_extensions=request.file_extensions,
+        root_folder_id=root_folder_id,
+        enable_summary=request.enable_summary,
+    )
+
+    return {
+        "message": "Folder indexing started",
+        "status": "processing",
+        "root_folder_id": root_folder_id,
+    }
+
+
+@router.post("/documents/folder-index-file")
+async def folder_index_file(
+    request: FolderIndexFileRequest,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Index a single file within a watched folder (chokidar trigger).
+    Validates that target_file_path is under folder_path.
+    """
+    from app.config import config as app_config
+
+    if not app_config.is_self_hosted():
+        raise HTTPException(
+            status_code=400,
+            detail="Local folder indexing is only available in self-hosted mode",
+        )
+
+    await check_permission(
+        session,
+        user,
+        request.search_space_id,
+        Permission.DOCUMENTS_CREATE.value,
+        "You don't have permission to create documents in this search space",
+    )
+
+    from pathlib import Path
+
+    try:
+        Path(request.target_file_path).relative_to(request.folder_path)
+    except ValueError:
+        raise HTTPException(
+            status_code=400,
+            detail="target_file_path must be inside folder_path",
+        )
+
+    from app.tasks.celery_tasks.document_tasks import index_local_folder_task
+
+    index_local_folder_task.delay(
+        search_space_id=request.search_space_id,
+        user_id=str(user.id),
+        folder_path=request.folder_path,
+        folder_name=request.folder_name,
+        target_file_path=request.target_file_path,
+        enable_summary=request.enable_summary,
+    )
+
+    return {
+        "message": "File indexing started",
+        "status": "processing",
+    }
diff --git a/surfsense_backend/app/routes/search_source_connectors_routes.py b/surfsense_backend/app/routes/search_source_connectors_routes.py
index 5ea88c418..f49ba2d5d 100644
--- a/surfsense_backend/app/routes/search_source_connectors_routes.py
+++ b/surfsense_backend/app/routes/search_source_connectors_routes.py
@@ -1170,24 +1170,6 @@ async def index_connector_content(
             )
             response_message = "Obsidian vault indexing started in the background."
 
-        elif connector.connector_type == SearchSourceConnectorType.LOCAL_FOLDER_CONNECTOR:
-            from app.config import config as app_config
-            from app.tasks.celery_tasks.connector_tasks import index_local_folder_task
-
-            if not app_config.is_self_hosted():
-                raise HTTPException(
-                    status_code=400,
-                    detail="Local folder connector is only available in self-hosted mode",
-                )
-
-            logger.info(
-                f"Triggering local folder indexing for connector {connector_id} into search space {search_space_id}"
-            )
-            index_local_folder_task.delay(
-                connector_id, search_space_id, str(user.id), indexing_from, indexing_to
-            )
-            response_message = "Local folder indexing started in the background."
-
         elif (
             connector.connector_type
             == SearchSourceConnectorType.COMPOSIO_GOOGLE_DRIVE_CONNECTOR
@@ -1320,76 +1302,6 @@ async def index_connector_content(
         ) from e
 
 
-class IndexFileRequest(BaseModel):
-    file_path: str = Field(..., description="Absolute path to the file to index")
-
-
-@router.post(
-    "/search-source-connectors/{connector_id}/index-file",
-    response_model=dict[str, Any],
-)
-async def index_single_file(
-    connector_id: int,
-    body: IndexFileRequest,
-    session: AsyncSession = Depends(get_async_session),
-    user: User = Depends(current_active_user),
-):
-    """Index a single file from a local folder connector (chokidar real-time trigger)."""
-    from app.config import config as app_config
-    from app.tasks.celery_tasks.connector_tasks import index_local_folder_task
-
-    if not app_config.is_self_hosted():
-        raise HTTPException(
-            status_code=400,
-            detail="Local folder connector is only available in self-hosted mode",
-        )
-
-    result = await session.execute(
-        select(SearchSourceConnector).filter(
-            SearchSourceConnector.id == connector_id,
-            SearchSourceConnector.connector_type
-            == SearchSourceConnectorType.LOCAL_FOLDER_CONNECTOR,
-        )
-    )
-    connector = result.scalars().first()
-    if not connector:
-        raise HTTPException(status_code=404, detail="Local folder connector not found")
-
-    await check_permission(session, user, connector.search_space_id, Permission.CONNECTORS_UPDATE.value)
-
-    folder_path = connector.config.get("folder_path", "")
-
-    # Security: resolve symlinks and verify the file is inside folder_path
-    try:
-        resolved_file = os.path.realpath(body.file_path)
-        resolved_folder = os.path.realpath(folder_path)
-        if not resolved_file.startswith(resolved_folder + os.sep) and resolved_file != resolved_folder:
-            raise HTTPException(
-                status_code=403,
-                detail="File path is outside the configured folder",
-            )
-    except (OSError, ValueError):
-        raise HTTPException(
-            status_code=403,
-            detail="Invalid file path",
-        )
-
-    index_local_folder_task.delay(
-        connector_id,
-        connector.search_space_id,
-        str(user.id),
-        None,
-        None,
-        target_file_path=resolved_file,
-    )
-
-    return {
-        "message": "Single file indexing started",
-        "connector_id": connector_id,
-        "file_path": body.file_path,
-    }
-
-
 async def _update_connector_timestamp_by_id(session: AsyncSession, connector_id: int):
     """
     Update the last_indexed_at timestamp for a connector by its ID.
@@ -3166,62 +3078,6 @@ async def run_obsidian_indexing(
     )
 
 
-async def run_local_folder_indexing_with_new_session(
-    connector_id: int,
-    search_space_id: int,
-    user_id: str,
-    start_date: str,
-    end_date: str,
-    target_file_path: str | None = None,
-):
-    """Wrapper to run local folder indexing with its own database session."""
-    logger.info(
-        f"Background task started: Indexing local folder connector {connector_id} into space {search_space_id}"
-    )
-    async with async_session_maker() as session:
-        await run_local_folder_indexing(
-            session, connector_id, search_space_id, user_id, start_date, end_date,
-            target_file_path=target_file_path,
-        )
-    logger.info(f"Background task finished: Indexing local folder connector {connector_id}")
-
-
-async def run_local_folder_indexing(
-    session: AsyncSession,
-    connector_id: int,
-    search_space_id: int,
-    user_id: str,
-    start_date: str,
-    end_date: str,
-    target_file_path: str | None = None,
-):
-    """Background task to run local folder indexing."""
-    from app.tasks.connector_indexers import index_local_folder
-
-    await _run_indexing_with_notifications(
-        session=session,
-        connector_id=connector_id,
-        search_space_id=search_space_id,
-        user_id=user_id,
-        start_date=start_date,
-        end_date=end_date,
-        indexing_function=lambda session, connector_id, search_space_id, user_id,
-        start_date, end_date, update_last_indexed, on_heartbeat_callback: index_local_folder(
-            session=session,
-            connector_id=connector_id,
-            search_space_id=search_space_id,
-            user_id=user_id,
-            start_date=start_date,
-            end_date=end_date,
-            update_last_indexed=update_last_indexed,
-            on_heartbeat_callback=on_heartbeat_callback,
-            target_file_path=target_file_path,
-        ),
-        update_timestamp_func=_update_connector_timestamp_by_id,
-        supports_heartbeat_callback=True,
-    )
-
-
 async def run_composio_indexing_with_new_session(
     connector_id: int,
     search_space_id: int,
diff --git a/surfsense_backend/app/tasks/celery_tasks/connector_tasks.py b/surfsense_backend/app/tasks/celery_tasks/connector_tasks.py
index 9ff578ad2..57475c9fd 100644
--- a/surfsense_backend/app/tasks/celery_tasks/connector_tasks.py
+++ b/surfsense_backend/app/tasks/celery_tasks/connector_tasks.py
@@ -926,52 +926,6 @@ async def _index_obsidian_vault(
         )
 
 
-@celery_app.task(name="index_local_folder", bind=True)
-def index_local_folder_task(
-    self,
-    connector_id: int,
-    search_space_id: int,
-    user_id: str,
-    start_date: str = None,
-    end_date: str = None,
-    target_file_path: str = None,
-):
-    """Celery task to index a local folder."""
-    import asyncio
-
-    loop = asyncio.new_event_loop()
-    asyncio.set_event_loop(loop)
-
-    try:
-        loop.run_until_complete(
-            _index_local_folder(
-                connector_id, search_space_id, user_id, start_date, end_date, target_file_path
-            )
-        )
-    finally:
-        loop.close()
-
-
-async def _index_local_folder(
-    connector_id: int,
-    search_space_id: int,
-    user_id: str,
-    start_date: str = None,
-    end_date: str = None,
-    target_file_path: str = None,
-):
-    """Index local folder with new session."""
-    from app.routes.search_source_connectors_routes import (
-        run_local_folder_indexing,
-    )
-
-    async with get_celery_session_maker()() as session:
-        await run_local_folder_indexing(
-            session, connector_id, search_space_id, user_id, start_date, end_date,
-            target_file_path=target_file_path,
-        )
-
-
 @celery_app.task(name="index_composio_connector", bind=True)
 def index_composio_connector_task(
     self,
diff --git a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
index 662b41f2a..110f3deee 100644
--- a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
+++ b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
@@ -10,6 +10,7 @@ from app.config import config
 from app.services.notification_service import NotificationService
 from app.services.task_logging_service import TaskLoggingService
 from app.tasks.celery_tasks import get_celery_session_maker
+from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
 from app.tasks.document_processors import (
     add_extension_received_document,
     add_youtube_video_document,
@@ -1243,3 +1244,68 @@ async def _process_circleback_meeting(
                 heartbeat_task.cancel()
             if notification:
                 _stop_heartbeat(notification.id)
+
+
+# ===== Local folder indexing task =====
+
+
+@celery_app.task(name="index_local_folder", bind=True)
+def index_local_folder_task(
+    self,
+    search_space_id: int,
+    user_id: str,
+    folder_path: str,
+    folder_name: str,
+    exclude_patterns: list[str] | None = None,
+    file_extensions: list[str] | None = None,
+    root_folder_id: int | None = None,
+    enable_summary: bool = False,
+    target_file_path: str | None = None,
+):
+    """Celery task to index a local folder. Config is passed directly — no connector row."""
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    try:
+        loop.run_until_complete(
+            _index_local_folder_async(
+                search_space_id=search_space_id,
+                user_id=user_id,
+                folder_path=folder_path,
+                folder_name=folder_name,
+                exclude_patterns=exclude_patterns,
+                file_extensions=file_extensions,
+                root_folder_id=root_folder_id,
+                enable_summary=enable_summary,
+                target_file_path=target_file_path,
+            )
+        )
+    finally:
+        loop.close()
+
+
+async def _index_local_folder_async(
+    search_space_id: int,
+    user_id: str,
+    folder_path: str,
+    folder_name: str,
+    exclude_patterns: list[str] | None = None,
+    file_extensions: list[str] | None = None,
+    root_folder_id: int | None = None,
+    enable_summary: bool = False,
+    target_file_path: str | None = None,
+):
+    """Run local folder indexing with a fresh DB session."""
+    async with get_celery_session_maker()() as session:
+        await index_local_folder(
+            session=session,
+            search_space_id=search_space_id,
+            user_id=user_id,
+            folder_path=folder_path,
+            folder_name=folder_name,
+            exclude_patterns=exclude_patterns,
+            file_extensions=file_extensions,
+            root_folder_id=root_folder_id,
+            enable_summary=enable_summary,
+            target_file_path=target_file_path,
+        )
diff --git a/surfsense_backend/app/tasks/connector_indexers/__init__.py b/surfsense_backend/app/tasks/connector_indexers/__init__.py
index 8e4ad69e5..1b032d54a 100644
--- a/surfsense_backend/app/tasks/connector_indexers/__init__.py
+++ b/surfsense_backend/app/tasks/connector_indexers/__init__.py
@@ -44,7 +44,6 @@ from .jira_indexer import index_jira_issues
 from .linear_indexer import index_linear_issues
 
 # Documentation and knowledge management
-from .local_folder_indexer import index_local_folder
 from .luma_indexer import index_luma_events
 from .notion_indexer import index_notion_pages
 from .obsidian_indexer import index_obsidian_vault
@@ -75,5 +74,4 @@ __all__ = [  # noqa: RUF022
     # Communication platforms
     "index_slack_messages",
     "index_google_gmail_messages",
-    "index_local_folder",
 ]
diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index fc7fdaf66..591914625 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -1,5 +1,5 @@
 """
-Local folder connector indexer.
+Local folder indexer.
 
 Indexes files from a local folder on disk. Supports:
 - Full-scan mode (startup reconciliation / manual trigger)
@@ -8,7 +8,9 @@ Indexes files from a local folder on disk. Supports:
 - Document versioning via create_version_snapshot
 - ETL-based file parsing for binary formats (PDF, DOCX, images, audio, etc.)
 
-Electron-only: all change detection is driven by chokidar in the desktop app.
+Desktop-only: all change detection is driven by chokidar in the desktop app.
+Config (folder_path, exclude_patterns, etc.) is passed in from the caller —
+no connector row is read.
 """
 
 import os
@@ -17,10 +19,9 @@ from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
 from pathlib import Path
 
-from sqlalchemy import delete, select
+from sqlalchemy import select
 from sqlalchemy.exc import SQLAlchemyError
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm.attributes import flag_modified
 
 from app.config import config
 from app.db import (
@@ -28,7 +29,6 @@ from app.db import (
     DocumentStatus,
     DocumentType,
     Folder,
-    SearchSourceConnectorType,
 )
 from app.services.llm_service import get_user_long_context_llm
 from app.services.task_logging_service import TaskLoggingService
@@ -45,11 +45,9 @@ from .base import (
     build_document_metadata_string,
     check_document_by_unique_identifier,
     check_duplicate_document_by_hash,
-    get_connector_by_id,
     get_current_timestamp,
     logger,
     safe_set_chunks,
-    update_connector_last_indexed,
 )
 
 PLAINTEXT_EXTENSIONS = frozenset({
@@ -131,12 +129,10 @@ def scan_folder(
     for dirpath, dirnames, filenames in os.walk(root):
         rel_dir = Path(dirpath).relative_to(root)
 
-        # Prune excluded directories in-place so os.walk skips them
         dirnames[:] = [
             d for d in dirnames if d not in exclude_patterns
         ]
 
-        # Check if the current directory itself is excluded
         if any(part in exclude_patterns for part in rel_dir.parts):
             continue
 
@@ -232,20 +228,18 @@ async def _mirror_folder_structure(
     folder_name: str,
     search_space_id: int,
     user_id: str,
-    connector_config: dict,
-    connector,
+    root_folder_id: int | None = None,
     exclude_patterns: list[str] | None = None,
-) -> dict[str, int]:
+) -> tuple[dict[str, int], int]:
     """Mirror the local filesystem directory structure into DB Folder rows.
 
-    Returns a mapping of relative_dir_path -> folder_id.
-    The empty string key ("") maps to the root folder.
+    Returns (mapping, root_folder_id) where mapping is
+    relative_dir_path -> folder_id. The empty string key maps to the root folder.
     """
     root = Path(folder_path)
     if exclude_patterns is None:
         exclude_patterns = []
 
-    # Collect all subdirectory paths relative to root
     subdirs: list[str] = []
     for dirpath, dirnames, _ in os.walk(root):
         dirnames[:] = [d for d in dirnames if d not in exclude_patterns]
@@ -256,13 +250,10 @@ async def _mirror_folder_structure(
         if rel_str:
             subdirs.append(rel_str)
 
-    # Sort by depth so parents are created before children
     subdirs.sort(key=lambda p: p.count(os.sep))
 
     mapping: dict[str, int] = {}
 
-    # Get or create root folder
-    root_folder_id = connector_config.get("root_folder_id")
     if root_folder_id:
         existing = (
             await session.execute(
@@ -284,12 +275,8 @@ async def _mirror_folder_structure(
         session.add(root_folder)
         await session.flush()
         mapping[""] = root_folder.id
-        # Persist root_folder_id into connector config
-        connector_config["root_folder_id"] = root_folder.id
-        connector.config = {**connector.config, "root_folder_id": root_folder.id}
-        flag_modified(connector, "config")
+        root_folder_id = root_folder.id
 
-    # Create/reuse subdirectory Folder rows
     for rel_dir in subdirs:
         dir_parts = Path(rel_dir).parts
         dir_name = dir_parts[-1]
@@ -322,7 +309,7 @@ async def _mirror_folder_structure(
             mapping[rel_dir] = new_folder.id
 
     await session.flush()
-    return mapping
+    return mapping, root_folder_id
 
 
 async def _cleanup_empty_folders(
@@ -332,16 +319,11 @@ async def _cleanup_empty_folders(
     existing_dirs_on_disk: set[str],
     folder_mapping: dict[str, int],
 ) -> None:
-    """Delete Folder rows that are empty (no docs, no children) and no longer on disk.
+    """Delete Folder rows that are empty (no docs, no children) and no longer on disk."""
+    from sqlalchemy import delete as sa_delete
 
-    Queries ALL folders under this search space (not just the current mapping)
-    so that stale folders from previous syncs are also cleaned up.
-    """
-    # Build a reverse mapping from folder_id → rel_dir for known dirs
     id_to_rel: dict[int, str] = {fid: rel for rel, fid in folder_mapping.items() if rel}
 
-    # Also find any folders in the DB that are children of the root but NOT
-    # in the current mapping (stale from a previous sync).
     all_folders = (
         await session.execute(
             select(Folder).where(
@@ -351,7 +333,6 @@ async def _cleanup_empty_folders(
         )
     ).scalars().all()
 
-    # Build candidates: folders not on disk that we might delete
     candidates: list[Folder] = []
     for folder in all_folders:
         rel = id_to_rel.get(folder.id)
@@ -359,8 +340,6 @@ async def _cleanup_empty_folders(
             continue
         candidates.append(folder)
 
-    # Sort deepest first (by name depth heuristic — folders with no children first)
-    # Repeat until no more deletions happen (cascading empty parents)
     changed = True
     while changed:
         changed = False
@@ -384,57 +363,46 @@ async def _cleanup_empty_folders(
                 remaining.append(folder)
                 continue
 
-            await session.execute(delete(Folder).where(Folder.id == folder.id))
+            await session.execute(sa_delete(Folder).where(Folder.id == folder.id))
             changed = True
         candidates = remaining
 
 
 async def index_local_folder(
     session: AsyncSession,
-    connector_id: int,
     search_space_id: int,
     user_id: str,
-    start_date: str | None = None,
-    end_date: str | None = None,
-    update_last_indexed: bool = True,
-    on_heartbeat_callback: HeartbeatCallbackType | None = None,
+    folder_path: str,
+    folder_name: str,
+    exclude_patterns: list[str] | None = None,
+    file_extensions: list[str] | None = None,
+    root_folder_id: int | None = None,
+    enable_summary: bool = False,
     target_file_path: str | None = None,
-) -> tuple[int, int, str | None]:
+    on_heartbeat_callback: HeartbeatCallbackType | None = None,
+) -> tuple[int, int, int | None, str | None]:
     """Index files from a local folder.
 
     Supports two modes:
     - Full scan (target_file_path=None): walks entire folder, handles new/changed/deleted files.
     - Single-file (target_file_path set): processes only that file.
 
-    Returns (indexed_count, skipped_count, error_or_warning_message).
+    Returns (indexed_count, skipped_count, root_folder_id, error_or_warning_message).
     """
     task_logger = TaskLoggingService(session, search_space_id)
 
     log_entry = await task_logger.log_task_start(
         task_name="local_folder_indexing",
-        source="connector_indexing_task",
-        message=f"Starting local folder indexing for connector {connector_id}",
+        source="local_folder_indexing_task",
+        message=f"Starting local folder indexing for {folder_name}",
         metadata={
-            "connector_id": connector_id,
+            "folder_path": folder_path,
             "user_id": str(user_id),
             "target_file_path": target_file_path,
         },
     )
 
     try:
-        connector = await get_connector_by_id(
-            session, connector_id, SearchSourceConnectorType.LOCAL_FOLDER_CONNECTOR
-        )
-        if not connector:
-            await task_logger.log_task_failure(
-                log_entry,
-                f"Connector {connector_id} not found",
-                "Connector not found",
-                {},
-            )
-            return 0, 0, f"Connector {connector_id} not found"
-
-        folder_path = connector.config.get("folder_path")
         if not folder_path or not os.path.exists(folder_path):
             await task_logger.log_task_failure(
                 log_entry,
@@ -442,59 +410,54 @@ async def index_local_folder(
                 "Folder not found",
                 {},
             )
-            return 0, 0, f"Folder path missing or does not exist: {folder_path}"
+            return 0, 0, root_folder_id, f"Folder path missing or does not exist: {folder_path}"
 
-        folder_name = connector.config.get("folder_name") or os.path.basename(folder_path)
-        exclude_patterns = connector.config.get("exclude_patterns", DEFAULT_EXCLUDE_PATTERNS)
-        file_extensions = connector.config.get("file_extensions")  # None = all
+        if exclude_patterns is None:
+            exclude_patterns = DEFAULT_EXCLUDE_PATTERNS
 
         # ====================================================================
         # SINGLE-FILE MODE
         # ====================================================================
         if target_file_path:
-            return await _index_single_file(
+            indexed, skipped, err = await _index_single_file(
                 session=session,
-                connector=connector,
-                connector_id=connector_id,
                 search_space_id=search_space_id,
                 user_id=user_id,
                 folder_path=folder_path,
                 folder_name=folder_name,
                 target_file_path=target_file_path,
+                enable_summary=enable_summary,
                 task_logger=task_logger,
                 log_entry=log_entry,
-                update_last_indexed=update_last_indexed,
             )
+            return indexed, skipped, root_folder_id, err
 
         # ====================================================================
         # FULL-SCAN MODE
         # ====================================================================
 
-        # Phase 0: Mirror folder structure
         await task_logger.log_task_progress(
             log_entry, "Mirroring folder structure", {"stage": "folder_mirror"}
         )
 
-        folder_mapping = await _mirror_folder_structure(
+        folder_mapping, root_folder_id = await _mirror_folder_structure(
             session=session,
             folder_path=folder_path,
             folder_name=folder_name,
             search_space_id=search_space_id,
             user_id=user_id,
-            connector_config=connector.config,
-            connector=connector,
+            root_folder_id=root_folder_id,
             exclude_patterns=exclude_patterns,
         )
         await session.flush()
 
-        # Scan files on disk
         try:
             files = scan_folder(folder_path, file_extensions, exclude_patterns)
         except Exception as e:
             await task_logger.log_task_failure(
                 log_entry, f"Failed to scan folder: {e}", "Scan error", {}
             )
-            return 0, 0, f"Failed to scan folder: {e}"
+            return 0, 0, root_folder_id, f"Failed to scan folder: {e}"
 
         logger.info(f"Found {len(files)} files in folder")
 
@@ -530,7 +493,6 @@ async def index_local_folder(
                 )
 
                 if existing_document:
-                    # Check mtime first (cheap)
                     stored_mtime = (existing_document.document_metadata or {}).get("mtime")
                     current_mtime = file_info["modified_at"].timestamp()
 
@@ -542,7 +504,6 @@ async def index_local_folder(
                         skipped_count += 1
                         continue
 
-                    # mtime differs — read file and check content hash
                     try:
                         content, content_hash = await _compute_file_content_hash(
                             file_path_abs, file_info["relative_path"], search_space_id
@@ -553,7 +514,6 @@ async def index_local_folder(
                         continue
 
                     if existing_document.content_hash == content_hash:
-                        # Content same, just update mtime in metadata
                         meta = dict(existing_document.document_metadata or {})
                         meta["mtime"] = current_mtime
                         existing_document.document_metadata = meta
@@ -564,7 +524,6 @@ async def index_local_folder(
                         skipped_count += 1
                         continue
 
-                    # Content actually changed — snapshot version, queue for re-index
                     await create_version_snapshot(session, existing_document)
 
                     files_to_process.append(
@@ -581,7 +540,6 @@ async def index_local_folder(
                     )
                     continue
 
-                # New document — read content
                 try:
                     content, content_hash = await _compute_file_content_hash(
                         file_path_abs, file_info["relative_path"], search_space_id
@@ -595,7 +553,6 @@ async def index_local_folder(
                     skipped_count += 1
                     continue
 
-                # Check for duplicate content from another connector
                 with session.no_autoflush:
                     dup = await check_duplicate_document_by_hash(session, content_hash)
                 if dup:
@@ -603,7 +560,6 @@ async def index_local_folder(
                     skipped_count += 1
                     continue
 
-                # Determine folder_id for this file
                 parent_dir = str(Path(relative_path).parent)
                 if parent_dir == ".":
                     parent_dir = ""
@@ -616,17 +572,16 @@ async def index_local_folder(
                     document_metadata={
                         "folder_name": folder_name,
                         "file_path": relative_path,
-                        "connector_id": connector_id,
                         "mtime": file_info["modified_at"].timestamp(),
                     },
                     content="Pending...",
-                    content_hash=unique_identifier_hash,  # Temp unique — updated in phase 2
+                    content_hash=unique_identifier_hash,
                     unique_identifier_hash=unique_identifier_hash,
                     embedding=None,
                     status=DocumentStatus.pending(),
                     updated_at=get_current_timestamp(),
                     created_by_id=user_id,
-                    connector_id=connector_id,
+                    connector_id=None,
                     folder_id=folder_id,
                 )
                 session.add(document)
@@ -655,16 +610,17 @@ async def index_local_folder(
         # ================================================================
         # PHASE 1.5: Delete documents no longer on disk
         # ================================================================
-        all_connector_docs = (
+        all_folder_docs = (
             await session.execute(
                 select(Document).where(
-                    Document.connector_id == connector_id,
                     Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == search_space_id,
+                    Document.folder_id.in_(list(folder_mapping.values())),
                 )
             )
         ).scalars().all()
 
-        for doc in all_connector_docs:
+        for doc in all_folder_docs:
             if doc.unique_identifier_hash not in seen_unique_hashes:
                 await session.delete(doc)
 
@@ -709,7 +665,7 @@ async def index_local_folder(
                 document_string = build_document_metadata_string(metadata_sections)
 
                 summary_content = ""
-                if long_context_llm and connector.enable_summary:
+                if long_context_llm and enable_summary:
                     doc_meta = {
                         "folder_name": folder_name,
                         "file_path": relative_path,
@@ -721,7 +677,6 @@ async def index_local_folder(
                 embedding = embed_text(document_string)
                 chunks = await create_document_chunks(document_string)
 
-                # Determine folder_id
                 parent_dir = str(Path(relative_path).parent)
                 if parent_dir == ".":
                     parent_dir = ""
@@ -735,7 +690,6 @@ async def index_local_folder(
                 document.document_metadata = {
                     "folder_name": folder_name,
                     "file_path": relative_path,
-                    "connector_id": connector_id,
                     "summary": summary_content,
                     "mtime": file_info["modified_at"].timestamp(),
                 }
@@ -782,8 +736,6 @@ async def index_local_folder(
                 session, root_fid, search_space_id, existing_dirs, folder_mapping
             )
 
-        await update_connector_last_indexed(session, connector, update_last_indexed)
-
         try:
             await session.commit()
         except Exception as e:
@@ -802,7 +754,7 @@ async def index_local_folder(
 
         await task_logger.log_task_success(
             log_entry,
-            f"Completed local folder indexing for connector {connector_id}",
+            f"Completed local folder indexing for {folder_name}",
             {
                 "indexed": indexed_count,
                 "skipped": skipped_count,
@@ -811,7 +763,7 @@ async def index_local_folder(
             },
         )
 
-        return indexed_count, skipped_count, warning_message
+        return indexed_count, skipped_count, root_folder_id, warning_message
 
     except SQLAlchemyError as e:
         logger.exception(f"Database error during local folder indexing: {e}")
@@ -819,34 +771,31 @@ async def index_local_folder(
         await task_logger.log_task_failure(
             log_entry, f"DB error: {e}", "Database error", {}
         )
-        return 0, 0, f"Database error: {e}"
+        return 0, 0, root_folder_id, f"Database error: {e}"
 
     except Exception as e:
         logger.exception(f"Error during local folder indexing: {e}")
         await task_logger.log_task_failure(
             log_entry, f"Error: {e}", "Unexpected error", {}
         )
-        return 0, 0, str(e)
+        return 0, 0, root_folder_id, str(e)
 
 
 async def _index_single_file(
     session: AsyncSession,
-    connector,
-    connector_id: int,
     search_space_id: int,
     user_id: str,
     folder_path: str,
     folder_name: str,
     target_file_path: str,
+    enable_summary: bool,
     task_logger,
     log_entry,
-    update_last_indexed: bool = True,
 ) -> tuple[int, int, str | None]:
     """Process a single file (chokidar real-time trigger)."""
     try:
         full_path = Path(target_file_path)
         if not full_path.exists():
-            # File was deleted — find and remove the document
             rel = str(full_path.relative_to(folder_path))
             unique_id = f"{folder_name}:{rel}"
             uid_hash = generate_unique_identifier_hash(
@@ -880,7 +829,6 @@ async def _index_single_file(
 
         if existing:
             if existing.content_hash == content_hash:
-                # Update mtime
                 mtime = full_path.stat().st_mtime
                 meta = dict(existing.document_metadata or {})
                 meta["mtime"] = mtime
@@ -888,10 +836,8 @@ async def _index_single_file(
                 await session.commit()
                 return 0, 1, None
 
-            # Content changed — snapshot + re-index
             await create_version_snapshot(session, existing)
 
-        # Get LLM
         long_context_llm = await get_user_long_context_llm(
             session, user_id, search_space_id
         )
@@ -906,7 +852,7 @@ async def _index_single_file(
         document_string = build_document_metadata_string(metadata_sections)
 
         summary_content = ""
-        if long_context_llm and connector.enable_summary:
+        if long_context_llm and enable_summary:
             summary_content, _ = await generate_document_summary(
                 document_string, long_context_llm, {"folder_name": folder_name, "file_path": rel_path}
             )
@@ -917,7 +863,6 @@ async def _index_single_file(
         doc_metadata = {
             "folder_name": folder_name,
             "file_path": rel_path,
-            "connector_id": connector_id,
             "summary": summary_content,
             "mtime": mtime,
         }
@@ -946,16 +891,14 @@ async def _index_single_file(
                 status=DocumentStatus.ready(),
                 updated_at=get_current_timestamp(),
                 created_by_id=user_id,
-                connector_id=connector_id,
+                connector_id=None,
             )
             session.add(document)
-            # Set chunks
             await session.flush()
             for chunk in chunks:
                 chunk.document_id = document.id
             session.add_all(chunks)
 
-        await update_connector_last_indexed(session, connector, update_last_indexed)
         await session.commit()
 
         await task_logger.log_task_success(
diff --git a/surfsense_backend/tests/integration/conftest.py b/surfsense_backend/tests/integration/conftest.py
index 840246e2f..9c91011ae 100644
--- a/surfsense_backend/tests/integration/conftest.py
+++ b/surfsense_backend/tests/integration/conftest.py
@@ -168,22 +168,3 @@ def make_connector_document(db_connector, db_user):
     return _make
 
 
-@pytest_asyncio.fixture
-async def db_local_folder_connector(
-    db_session: AsyncSession, db_user: User, db_search_space: SearchSpace, tmp_path
-) -> SearchSourceConnector:
-    connector = SearchSourceConnector(
-        name="Test Local Folder",
-        connector_type=SearchSourceConnectorType.LOCAL_FOLDER_CONNECTOR,
-        config={
-            "folder_path": str(tmp_path),
-            "folder_name": "test-folder",
-            "exclude_patterns": [],
-            "file_extensions": None,
-        },
-        search_space_id=db_search_space.id,
-        user_id=db_user.id,
-    )
-    db_session.add(connector)
-    await db_session.flush()
-    return connector
diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index 988905f8f..e46d59a67 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -14,7 +14,6 @@ from app.db import (
     DocumentType,
     DocumentVersion,
     Folder,
-    SearchSourceConnector,
     SearchSpace,
     User,
 )
@@ -72,7 +71,6 @@ class TestFullIndexer:
     async def test_i1_new_file_indexed(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
@@ -82,11 +80,12 @@ class TestFullIndexer:
 
         (tmp_path / "note.md").write_text("# Hello World\n\nContent here.")
 
-        count, skipped, err = await index_local_folder(
+        count, skipped, root_folder_id, err = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
         )
 
         assert err is None
@@ -95,7 +94,8 @@ class TestFullIndexer:
         docs = (
             await db_session.execute(
                 select(Document).where(
-                    Document.connector_id == db_local_folder_connector.id
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
                 )
             )
         ).scalars().all()
@@ -112,7 +112,6 @@ class TestFullIndexer:
     async def test_i2_unchanged_skipped(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
@@ -122,27 +121,31 @@ class TestFullIndexer:
 
         (tmp_path / "note.md").write_text("# Hello\n\nSame content.")
 
-        count1, _, _ = await index_local_folder(
+        count1, _, root_folder_id, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
         )
         assert count1 == 1
 
-        # Second run — unchanged
-        count2, _, _ = await index_local_folder(
+        # Second run — unchanged, pass root_folder_id from first run
+        count2, _, _, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            root_folder_id=root_folder_id,
         )
         assert count2 == 0
 
         total = (
             await db_session.execute(
                 select(func.count()).select_from(Document).where(
-                    Document.connector_id == db_local_folder_connector.id
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
                 )
             )
         ).scalar_one()
@@ -157,7 +160,6 @@ class TestFullIndexer:
     async def test_i3_changed_reindexed(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
@@ -168,11 +170,12 @@ class TestFullIndexer:
         f = tmp_path / "note.md"
         f.write_text("# Version 1\n\nOriginal.")
 
-        await index_local_folder(
+        _, _, root_folder_id, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
         )
 
         # Modify
@@ -180,11 +183,13 @@ class TestFullIndexer:
         # Touch mtime to ensure it's detected as different
         os.utime(f, (f.stat().st_atime + 10, f.stat().st_mtime + 10))
 
-        count, _, _ = await index_local_folder(
+        count, _, _, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            root_folder_id=root_folder_id,
         )
         assert count == 1
 
@@ -192,7 +197,8 @@ class TestFullIndexer:
         versions = (
             await db_session.execute(
                 select(DocumentVersion).join(Document).where(
-                    Document.connector_id == db_local_folder_connector.id
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
                 )
             )
         ).scalars().all()
@@ -207,7 +213,6 @@ class TestFullIndexer:
     async def test_i4_deleted_removed(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
@@ -218,17 +223,19 @@ class TestFullIndexer:
         f = tmp_path / "to_delete.md"
         f.write_text("# Delete me")
 
-        await index_local_folder(
+        _, _, root_folder_id, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
         )
 
         docs_before = (
             await db_session.execute(
                 select(func.count()).select_from(Document).where(
-                    Document.connector_id == db_local_folder_connector.id
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
                 )
             )
         ).scalar_one()
@@ -238,15 +245,18 @@ class TestFullIndexer:
 
         await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            root_folder_id=root_folder_id,
         )
 
         docs_after = (
             await db_session.execute(
                 select(func.count()).select_from(Document).where(
-                    Document.connector_id == db_local_folder_connector.id
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
                 )
             )
         ).scalar_one()
@@ -261,7 +271,6 @@ class TestFullIndexer:
     async def test_i5_single_file_mode(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
@@ -273,11 +282,12 @@ class TestFullIndexer:
         (tmp_path / "b.md").write_text("File B")
         (tmp_path / "c.md").write_text("File C")
 
-        count, _, _ = await index_local_folder(
+        count, _, _, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
             target_file_path=str(tmp_path / "b.md"),
         )
         assert count == 1
@@ -285,12 +295,13 @@ class TestFullIndexer:
         docs = (
             await db_session.execute(
                 select(Document).where(
-                    Document.connector_id == db_local_folder_connector.id
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
                 )
             )
         ).scalars().all()
         assert len(docs) == 1
-        assert docs[0].title == "b"
+        assert docs[0].title == "b.md"
 
 
 # ====================================================================
@@ -309,30 +320,27 @@ class TestFolderMirroring:
     async def test_f1_root_folder_created(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
     ):
-        """F1: First sync creates a root Folder and stores root_folder_id."""
+        """F1: First sync creates a root Folder and returns root_folder_id."""
         from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
 
         (tmp_path / "root.md").write_text("Root file")
 
-        await index_local_folder(
+        _, _, root_folder_id, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
         )
 
-        # Refresh connector
-        await db_session.refresh(db_local_folder_connector)
-        root_id = db_local_folder_connector.config.get("root_folder_id")
-        assert root_id is not None
+        assert root_folder_id is not None
 
         root_folder = (
-            await db_session.execute(select(Folder).where(Folder.id == root_id))
+            await db_session.execute(select(Folder).where(Folder.id == root_folder_id))
         ).scalar_one()
         assert root_folder.name == "test-folder"
 
@@ -345,7 +353,6 @@ class TestFolderMirroring:
     async def test_f2_nested_folder_rows(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
@@ -362,9 +369,10 @@ class TestFolderMirroring:
 
         await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
         )
 
         folders = (
@@ -394,7 +402,6 @@ class TestFolderMirroring:
     async def test_f3_resync_reuses_folders(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
@@ -406,11 +413,12 @@ class TestFolderMirroring:
         sub.mkdir()
         (sub / "file.md").write_text("content")
 
-        await index_local_folder(
+        _, _, root_folder_id, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
         )
 
         folders_before = (
@@ -420,12 +428,14 @@ class TestFolderMirroring:
         ).scalars().all()
         ids_before = {f.id for f in folders_before}
 
-        # Re-sync
+        # Re-sync with root_folder_id from first run
         await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            root_folder_id=root_folder_id,
         )
 
         folders_after = (
@@ -446,7 +456,6 @@ class TestFolderMirroring:
     async def test_f4_folder_id_assigned(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
@@ -459,17 +468,19 @@ class TestFolderMirroring:
         (daily / "today.md").write_text("today note")
         (tmp_path / "root.md").write_text("root note")
 
-        await index_local_folder(
+        _, _, root_folder_id, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
         )
 
         docs = (
             await db_session.execute(
                 select(Document).where(
-                    Document.connector_id == db_local_folder_connector.id
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
                 )
             )
         ).scalars().all()
@@ -486,9 +497,7 @@ class TestFolderMirroring:
         assert today_doc.folder_id == daily_folder.id
 
         # Root doc should be in the root folder
-        await db_session.refresh(db_local_folder_connector)
-        root_fid = db_local_folder_connector.config.get("root_folder_id")
-        assert root_doc.folder_id == root_fid
+        assert root_doc.folder_id == root_folder_id
 
     @pytest.mark.usefixtures(
         "patched_self_hosted",
@@ -499,7 +508,6 @@ class TestFolderMirroring:
     async def test_f5_empty_folder_cleanup(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         tmp_path: Path,
@@ -515,11 +523,12 @@ class TestFolderMirroring:
         (daily / "today.md").write_text("today")
         (weekly / "review.md").write_text("review")
 
-        await index_local_folder(
+        _, _, root_folder_id, _ = await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
         )
 
         # Verify weekly folder exists
@@ -535,9 +544,11 @@ class TestFolderMirroring:
 
         await index_local_folder(
             session=db_session,
-            connector_id=db_local_folder_connector.id,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            root_folder_id=root_folder_id,
         )
 
         # weekly Folder should be gone (empty, dir removed)
@@ -570,7 +581,6 @@ class TestPipelineIntegration:
     async def test_p1_local_folder_file_through_pipeline(
         self,
         db_session: AsyncSession,
-        db_local_folder_connector: SearchSourceConnector,
         db_user: User,
         db_search_space: SearchSpace,
         mocker,
@@ -585,7 +595,7 @@ class TestPipelineIntegration:
             unique_id="test-folder:test.md",
             document_type=DocumentType.LOCAL_FOLDER_FILE,
             search_space_id=db_search_space.id,
-            connector_id=db_local_folder_connector.id,
+            connector_id=None,
             created_by_id=str(db_user.id),
         )
 

From caf2525ab5d32ffbb6db0c96a5e4109996a24030 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 22:29:07 +0530
Subject: [PATCH 28/70] fix: update folder ID collection logic to include
 deleted directories and adjust test cases for document titles

---
 .../connector_indexers/local_folder_indexer.py    | 15 ++++++++++++++-
 .../test_local_folder_pipeline.py                 |  4 ++--
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index 591914625..93c6649a2 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -610,12 +610,25 @@ async def index_local_folder(
         # ================================================================
         # PHASE 1.5: Delete documents no longer on disk
         # ================================================================
+        # Collect ALL folder IDs under this root (including folders that no
+        # longer exist on disk but still have rows in the DB) so we catch
+        # documents in deleted directories too.
+        all_root_folder_ids = set(folder_mapping.values())
+        all_db_folders = (
+            await session.execute(
+                select(Folder.id).where(
+                    Folder.search_space_id == search_space_id,
+                )
+            )
+        ).scalars().all()
+        all_root_folder_ids.update(all_db_folders)
+
         all_folder_docs = (
             await session.execute(
                 select(Document).where(
                     Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
                     Document.search_space_id == search_space_id,
-                    Document.folder_id.in_(list(folder_mapping.values())),
+                    Document.folder_id.in_(list(all_root_folder_ids)),
                 )
             )
         ).scalars().all()
diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index e46d59a67..34efad789 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -485,8 +485,8 @@ class TestFolderMirroring:
             )
         ).scalars().all()
 
-        today_doc = next(d for d in docs if d.title == "today")
-        root_doc = next(d for d in docs if d.title == "root")
+        today_doc = next(d for d in docs if d.title == "today.md")
+        root_doc = next(d for d in docs if d.title == "root.md")
 
         daily_folder = (
             await db_session.execute(

From c27d24a117633aac32de889b12f153239b58a832 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 22:41:45 +0530
Subject: [PATCH 29/70] feat: enhance folder indexing by adding root folder ID
 support and implement folder creation and cleanup logic

---
 .../app/routes/documents_routes.py            |   2 +
 .../local_folder_indexer.py                   | 102 ++++++++++++++
 .../test_local_folder_pipeline.py             | 130 ++++++++++++++++++
 surfsense_web/hooks/use-folder-sync.ts        |   1 +
 .../lib/apis/documents-api.service.ts         |   2 +-
 5 files changed, 236 insertions(+), 1 deletion(-)

diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index d7974f9ff..05221b192 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -1280,6 +1280,7 @@ class FolderIndexFileRequest(PydanticBaseModel):
     folder_name: str
     search_space_id: int
     target_file_path: str
+    root_folder_id: int | None = None
     enable_summary: bool = False
 
 
@@ -1394,6 +1395,7 @@ async def folder_index_file(
         folder_path=request.folder_path,
         folder_name=request.folder_name,
         target_file_path=request.target_file_path,
+        root_folder_id=request.root_folder_id,
         enable_summary=request.enable_summary,
     )
 
diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index 93c6649a2..3d4ddc19e 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -312,6 +312,92 @@ async def _mirror_folder_structure(
     return mapping, root_folder_id
 
 
+async def _resolve_folder_for_file(
+    session: AsyncSession,
+    rel_path: str,
+    root_folder_id: int,
+    search_space_id: int,
+    user_id: str,
+) -> int:
+    """Given a file's relative path, ensure all parent Folder rows exist and
+    return the folder_id for the file's immediate parent directory.
+
+    For a file at "notes/daily/today.md", this ensures Folder rows exist for
+    "notes" and "notes/daily", and returns the id of "notes/daily".
+    For a file at "readme.md" (root level), returns root_folder_id.
+    """
+    parent_dir = str(Path(rel_path).parent)
+    if parent_dir == ".":
+        return root_folder_id
+
+    parts = Path(parent_dir).parts
+    current_parent_id = root_folder_id
+
+    for part in parts:
+        existing = (
+            await session.execute(
+                select(Folder).where(
+                    Folder.name == part,
+                    Folder.parent_id == current_parent_id,
+                    Folder.search_space_id == search_space_id,
+                )
+            )
+        ).scalar_one_or_none()
+
+        if existing:
+            current_parent_id = existing.id
+        else:
+            new_folder = Folder(
+                name=part,
+                parent_id=current_parent_id,
+                search_space_id=search_space_id,
+                created_by_id=user_id,
+                position="a0",
+            )
+            session.add(new_folder)
+            await session.flush()
+            current_parent_id = new_folder.id
+
+    return current_parent_id
+
+
+async def _cleanup_empty_folder_chain(
+    session: AsyncSession,
+    folder_id: int,
+    root_folder_id: int,
+) -> None:
+    """Walk up from folder_id toward root, deleting empty folders (no docs, no
+    children). Stops at root_folder_id which is never deleted."""
+    current_id = folder_id
+    while current_id and current_id != root_folder_id:
+        has_doc = (
+            await session.execute(
+                select(Document.id).where(Document.folder_id == current_id).limit(1)
+            )
+        ).scalar_one_or_none()
+        if has_doc is not None:
+            break
+
+        has_child = (
+            await session.execute(
+                select(Folder.id).where(Folder.parent_id == current_id).limit(1)
+            )
+        ).scalar_one_or_none()
+        if has_child is not None:
+            break
+
+        folder = (
+            await session.execute(select(Folder).where(Folder.id == current_id))
+        ).scalar_one_or_none()
+        if not folder:
+            break
+
+        parent_id = folder.parent_id
+        await session.delete(folder)
+        await session.flush()
+        current_id = parent_id
+
+
 async def _cleanup_empty_folders(
     session: AsyncSession,
     root_folder_id: int,
@@ -427,6 +513,7 @@ async def index_local_folder(
                 folder_name=folder_name,
                 target_file_path=target_file_path,
                 enable_summary=enable_summary,
+                root_folder_id=root_folder_id,
                 task_logger=task_logger,
                 log_entry=log_entry,
             )
@@ -802,6 +889,7 @@ async def _index_single_file(
     folder_name: str,
     target_file_path: str,
     enable_summary: bool,
+    root_folder_id: int | None,
     task_logger,
     log_entry,
 ) -> tuple[int, int, str | None]:
@@ -816,7 +904,13 @@ async def _index_single_file(
             )
             existing = await check_document_by_unique_identifier(session, uid_hash)
             if existing:
+                deleted_folder_id = existing.folder_id
                 await session.delete(existing)
+                await session.flush()
+                if deleted_folder_id and root_folder_id:
+                    await _cleanup_empty_folder_chain(
+                        session, deleted_folder_id, root_folder_id
+                    )
                 await session.commit()
                 return 0, 0, None
             return 0, 0, None
@@ -880,6 +974,12 @@ async def _index_single_file(
             "mtime": mtime,
         }
 
+        folder_id = None
+        if root_folder_id:
+            folder_id = await _resolve_folder_for_file(
+                session, rel_path, root_folder_id, search_space_id, user_id
+            )
+
         if existing:
             existing.title = title
             existing.content = document_string
@@ -887,6 +987,7 @@ async def _index_single_file(
             existing.source_markdown = content
             existing.embedding = embedding
             existing.document_metadata = doc_metadata
+            existing.folder_id = folder_id
             await safe_set_chunks(session, existing, chunks)
             existing.updated_at = get_current_timestamp()
             existing.status = DocumentStatus.ready()
@@ -905,6 +1006,7 @@ async def _index_single_file(
                 updated_at=get_current_timestamp(),
                 created_by_id=user_id,
                 connector_id=None,
+                folder_id=folder_id,
             )
             session.add(document)
             await session.flush()
diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index 34efad789..110aa6caf 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -567,6 +567,136 @@ class TestFolderMirroring:
         ).scalar_one_or_none()
         assert daily_after is not None
 
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_f6_single_file_creates_subfolder(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """F6: Single-file mode creates missing Folder rows and assigns correct folder_id."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "root.md").write_text("root")
+
+        _, _, root_folder_id, _ = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+        )
+
+        sub = tmp_path / "notes" / "daily"
+        sub.mkdir(parents=True)
+        (sub / "new.md").write_text("new note in subfolder")
+
+        count, _, _, _ = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            target_file_path=str(sub / "new.md"),
+            root_folder_id=root_folder_id,
+        )
+        assert count == 1
+
+        doc = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.title == "new.md",
+                )
+            )
+        ).scalar_one()
+
+        daily_folder = (
+            await db_session.execute(
+                select(Folder).where(Folder.name == "daily")
+            )
+        ).scalar_one()
+
+        assert doc.folder_id == daily_folder.id
+        assert daily_folder.parent_id is not None
+
+        notes_folder = (
+            await db_session.execute(
+                select(Folder).where(Folder.name == "notes")
+            )
+        ).scalar_one()
+        assert daily_folder.parent_id == notes_folder.id
+        assert notes_folder.parent_id == root_folder_id
+
+    @pytest.mark.usefixtures(
+        "patched_self_hosted",
+        "patched_embed_for_indexer",
+        "patched_chunks_for_indexer",
+        "patched_summary_for_indexer",
+    )
+    async def test_f7_single_file_delete_cleans_empty_folders(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """F7: Deleting the only file in a subfolder via single-file mode removes empty Folder rows."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        sub = tmp_path / "notes" / "ephemeral"
+        sub.mkdir(parents=True)
+        (sub / "temp.md").write_text("temporary")
+        (tmp_path / "keep.md").write_text("keep this")
+
+        _, _, root_folder_id, _ = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+        )
+
+        eph_folder = (
+            await db_session.execute(
+                select(Folder).where(Folder.name == "ephemeral")
+            )
+        ).scalar_one_or_none()
+        assert eph_folder is not None
+
+        target = sub / "temp.md"
+        target.unlink()
+
+        await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            target_file_path=str(target),
+            root_folder_id=root_folder_id,
+        )
+
+        eph_after = (
+            await db_session.execute(
+                select(Folder).where(Folder.name == "ephemeral")
+            )
+        ).scalar_one_or_none()
+        assert eph_after is None
+
+        notes_after = (
+            await db_session.execute(
+                select(Folder).where(Folder.name == "notes")
+            )
+        ).scalar_one_or_none()
+        assert notes_after is None
+
 
 # ====================================================================
 # Tier 5: Pipeline Integration (P1)
diff --git a/surfsense_web/hooks/use-folder-sync.ts b/surfsense_web/hooks/use-folder-sync.ts
index fcfb2814e..f051b7df6 100644
--- a/surfsense_web/hooks/use-folder-sync.ts
+++ b/surfsense_web/hooks/use-folder-sync.ts
@@ -32,6 +32,7 @@ export function useFolderSync() {
 					folder_name: event.folderName,
 					search_space_id: event.searchSpaceId,
 					target_file_path: event.fullPath,
+					root_folder_id: event.rootFolderId,
 				});
 			} catch (err) {
 				console.error("[FolderSync] Failed to trigger re-index:", err);
diff --git a/surfsense_web/lib/apis/documents-api.service.ts b/surfsense_web/lib/apis/documents-api.service.ts
index c77cd6848..a8e3831d4 100644
--- a/surfsense_web/lib/apis/documents-api.service.ts
+++ b/surfsense_web/lib/apis/documents-api.service.ts
@@ -399,7 +399,7 @@ class DocumentsApiService {
 		return baseApiService.post(`/api/v1/documents/folder-index`, undefined, { body });
 	};
 
-	folderIndexFile = async (searchSpaceId: number, body: { folder_path: string; folder_name: string; search_space_id: number; target_file_path: string; enable_summary?: boolean }) => {
+	folderIndexFile = async (searchSpaceId: number, body: { folder_path: string; folder_name: string; search_space_id: number; target_file_path: string; root_folder_id?: number | null; enable_summary?: boolean }) => {
 		return baseApiService.post(`/api/v1/documents/folder-index-file`, undefined, { body });
 	};
 

From 53df393cf7ca300e9eb79f14429bb94857bde492 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 23:28:23 +0530
Subject: [PATCH 30/70] refactor: streamline local folder indexing logic by
 removing unused imports, enhancing content hashing, and improving document
 creation process

---
 .../local_folder_indexer.py                   | 415 +++++++-----------
 .../test_local_folder_pipeline.py             | 139 +-----
 2 files changed, 174 insertions(+), 380 deletions(-)

diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index 3d4ddc19e..a3281eaea 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -14,7 +14,6 @@ no connector row is read.
 """
 
 import os
-import time
 from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
 from pathlib import Path
@@ -30,24 +29,16 @@ from app.db import (
     DocumentType,
     Folder,
 )
+from app.indexing_pipeline.connector_document import ConnectorDocument
+from app.indexing_pipeline.document_hashing import compute_identifier_hash
+from app.indexing_pipeline.indexing_pipeline_service import IndexingPipelineService
 from app.services.llm_service import get_user_long_context_llm
 from app.services.task_logging_service import TaskLoggingService
-from app.utils.document_converters import (
-    create_document_chunks,
-    embed_text,
-    generate_content_hash,
-    generate_document_summary,
-    generate_unique_identifier_hash,
-)
 from app.utils.document_versioning import create_version_snapshot
 
 from .base import (
-    build_document_metadata_string,
     check_document_by_unique_identifier,
-    check_duplicate_document_by_hash,
-    get_current_timestamp,
     logger,
-    safe_set_chunks,
 )
 
 PLAINTEXT_EXTENSIONS = frozenset({
@@ -89,7 +80,6 @@ def _needs_etl(filename: str) -> bool:
     return not _is_plaintext_file(filename) and not _is_audio_file(filename)
 
 HeartbeatCallbackType = Callable[[int], Awaitable[None]]
-HEARTBEAT_INTERVAL_SECONDS = 30
 
 DEFAULT_EXCLUDE_PATTERNS = [
     ".git",
@@ -210,6 +200,16 @@ async def _read_file_content(file_path: str, filename: str) -> str:
     return await _parse_file_to_markdown(file_path, filename)
 
 
+def _content_hash(content: str, search_space_id: int) -> str:
+    """SHA-256 hash of content scoped to a search space.
+
+    Matches the format used by ``compute_content_hash`` in the unified
+    pipeline so that dedup checks are consistent.
+    """
+    import hashlib
+    return hashlib.sha256(f"{search_space_id}:{content}".encode("utf-8")).hexdigest()
+
+
 async def _compute_file_content_hash(
     file_path: str, filename: str, search_space_id: int,
 ) -> tuple[str, str]:
@@ -218,8 +218,7 @@ async def _compute_file_content_hash(
     Returns (content_text, content_hash).
     """
     content = await _read_file_content(file_path, filename)
-    content_hash = generate_content_hash(content, search_space_id)
-    return content, content_hash
+    return content, _content_hash(content, search_space_id)
 
 
 async def _mirror_folder_structure(
@@ -454,6 +453,40 @@ async def _cleanup_empty_folders(
         candidates = remaining
 
 
+def _build_connector_doc(
+    title: str,
+    content: str,
+    relative_path: str,
+    folder_name: str,
+    *,
+    search_space_id: int,
+    user_id: str,
+    enable_summary: bool,
+) -> ConnectorDocument:
+    """Build a ConnectorDocument from a local file's extracted content."""
+    unique_id = f"{folder_name}:{relative_path}"
+    metadata = {
+        "folder_name": folder_name,
+        "file_path": relative_path,
+        "document_type": "Local Folder File",
+        "connector_type": "Local Folder",
+    }
+    fallback_summary = f"File: {title}\n\n{content[:4000]}"
+
+    return ConnectorDocument(
+        title=title,
+        source_markdown=content,
+        unique_id=unique_id,
+        document_type=DocumentType.LOCAL_FOLDER_FILE,
+        search_space_id=search_space_id,
+        connector_id=None,
+        created_by_id=user_id,
+        should_summarize=enable_summary,
+        fallback_summary=fallback_summary,
+        metadata=metadata,
+    )
+
+
 async def index_local_folder(
     session: AsyncSession,
     search_space_id: int,
@@ -551,15 +584,13 @@ async def index_local_folder(
         indexed_count = 0
         skipped_count = 0
         failed_count = 0
-        duplicate_count = 0
-
-        last_heartbeat_time = time.time()
 
         # ================================================================
-        # PHASE 1: Analyze all files, create pending documents
+        # PHASE 1: Pre-filter files (mtime / content-hash), version changed
         # ================================================================
-        files_to_process: list[dict] = []
-        new_documents_created = False
+        connector_docs: list[ConnectorDocument] = []
+        # Maps unique_id -> (relative_path, mtime) for post-pipeline folder_id assignment
+        file_meta_map: dict[str, dict] = {}
         seen_unique_hashes: set[str] = set()
 
         for file_info in files:
@@ -568,8 +599,8 @@ async def index_local_folder(
                 file_path_abs = file_info["path"]
 
                 unique_identifier = f"{folder_name}:{relative_path}"
-                unique_identifier_hash = generate_unique_identifier_hash(
-                    DocumentType.LOCAL_FOLDER_FILE,
+                unique_identifier_hash = compute_identifier_hash(
+                    DocumentType.LOCAL_FOLDER_FILE.value,
                     unique_identifier,
                     search_space_id,
                 )
@@ -612,94 +643,42 @@ async def index_local_folder(
                         continue
 
                     await create_version_snapshot(session, existing_document)
+                else:
+                    try:
+                        content, content_hash = await _compute_file_content_hash(
+                            file_path_abs, file_info["relative_path"], search_space_id
+                        )
+                    except Exception as read_err:
+                        logger.warning(f"Could not read {file_path_abs}: {read_err}")
+                        skipped_count += 1
+                        continue
 
-                    files_to_process.append(
-                        {
-                            "document": existing_document,
-                            "is_new": False,
-                            "file_info": file_info,
-                            "content": content,
-                            "content_hash": content_hash,
-                            "unique_identifier_hash": unique_identifier_hash,
-                            "relative_path": relative_path,
-                            "title": file_info["name"],
-                        }
-                    )
-                    continue
+                    if not content.strip():
+                        skipped_count += 1
+                        continue
 
-                try:
-                    content, content_hash = await _compute_file_content_hash(
-                        file_path_abs, file_info["relative_path"], search_space_id
-                    )
-                except Exception as read_err:
-                    logger.warning(f"Could not read {file_path_abs}: {read_err}")
-                    skipped_count += 1
-                    continue
-
-                if not content.strip():
-                    skipped_count += 1
-                    continue
-
-                with session.no_autoflush:
-                    dup = await check_duplicate_document_by_hash(session, content_hash)
-                if dup:
-                    duplicate_count += 1
-                    skipped_count += 1
-                    continue
-
-                parent_dir = str(Path(relative_path).parent)
-                if parent_dir == ".":
-                    parent_dir = ""
-                folder_id = folder_mapping.get(parent_dir, folder_mapping.get(""))
-
-                document = Document(
-                    search_space_id=search_space_id,
+                doc = _build_connector_doc(
                     title=file_info["name"],
-                    document_type=DocumentType.LOCAL_FOLDER_FILE,
-                    document_metadata={
-                        "folder_name": folder_name,
-                        "file_path": relative_path,
-                        "mtime": file_info["modified_at"].timestamp(),
-                    },
-                    content="Pending...",
-                    content_hash=unique_identifier_hash,
-                    unique_identifier_hash=unique_identifier_hash,
-                    embedding=None,
-                    status=DocumentStatus.pending(),
-                    updated_at=get_current_timestamp(),
-                    created_by_id=user_id,
-                    connector_id=None,
-                    folder_id=folder_id,
-                )
-                session.add(document)
-                new_documents_created = True
-
-                files_to_process.append(
-                    {
-                        "document": document,
-                        "is_new": True,
-                        "file_info": file_info,
-                        "content": content,
-                        "content_hash": content_hash,
-                        "unique_identifier_hash": unique_identifier_hash,
-                        "relative_path": relative_path,
-                        "title": file_info["name"],
-                    }
+                    content=content,
+                    relative_path=relative_path,
+                    folder_name=folder_name,
+                    search_space_id=search_space_id,
+                    user_id=user_id,
+                    enable_summary=enable_summary,
                 )
+                connector_docs.append(doc)
+                file_meta_map[unique_identifier] = {
+                    "relative_path": relative_path,
+                    "mtime": file_info["modified_at"].timestamp(),
+                }
 
             except Exception as e:
                 logger.exception(f"Phase 1 error for {file_info.get('path')}: {e}")
                 failed_count += 1
 
-        if new_documents_created:
-            await session.commit()
-
         # ================================================================
         # PHASE 1.5: Delete documents no longer on disk
         # ================================================================
-        # Collect ALL folder IDs under this root (including folders that no
-        # longer exist on disk but still have rows in the DB) so we catch
-        # documents in deleted directories too.
         all_root_folder_ids = set(folder_mapping.values())
         all_db_folders = (
             await session.execute(
@@ -727,98 +706,51 @@ async def index_local_folder(
         await session.flush()
 
         # ================================================================
-        # PHASE 2: Process each document
+        # PHASE 2: Index via unified pipeline
         # ================================================================
-        long_context_llm = await get_user_long_context_llm(
-            session, user_id, search_space_id
-        )
+        if connector_docs:
+            from app.indexing_pipeline.document_hashing import (
+                compute_unique_identifier_hash,
+            )
 
-        for item in files_to_process:
-            if on_heartbeat_callback:
-                current_time = time.time()
-                if current_time - last_heartbeat_time >= HEARTBEAT_INTERVAL_SECONDS:
+            pipeline = IndexingPipelineService(session)
+            doc_map = {
+                compute_unique_identifier_hash(cd): cd for cd in connector_docs
+            }
+            documents = await pipeline.prepare_for_indexing(connector_docs)
+
+            llm = await get_user_long_context_llm(session, user_id, search_space_id)
+
+            for document in documents:
+                connector_doc = doc_map.get(document.unique_identifier_hash)
+                if connector_doc is None:
+                    failed_count += 1
+                    continue
+
+                result = await pipeline.index(document, connector_doc, llm)
+
+                if DocumentStatus.is_state(result.status, DocumentStatus.READY):
+                    indexed_count += 1
+
+                    # Assign folder_id and mtime post-pipeline
+                    rel_path = (connector_doc.metadata or {}).get("file_path", "")
+                    parent_dir = str(Path(rel_path).parent) if rel_path else ""
+                    if parent_dir == ".":
+                        parent_dir = ""
+                    fid = folder_mapping.get(parent_dir, folder_mapping.get(""))
+
+                    unique_id = connector_doc.unique_id
+                    mtime_info = file_meta_map.get(unique_id, {})
+
+                    result.folder_id = fid
+                    doc_meta = dict(result.document_metadata or {})
+                    doc_meta["mtime"] = mtime_info.get("mtime")
+                    result.document_metadata = doc_meta
+                else:
+                    failed_count += 1
+
+                if on_heartbeat_callback and indexed_count % 5 == 0:
                     await on_heartbeat_callback(indexed_count)
-                    last_heartbeat_time = current_time
-
-            document = item["document"]
-            try:
-                document.status = DocumentStatus.processing()
-                await session.commit()
-
-                title = item["title"]
-                relative_path = item["relative_path"]
-                content = item["content"]
-                content_hash = item["content_hash"]
-                file_info = item["file_info"]
-
-                metadata_sections = [
-                    (
-                        "METADATA",
-                        [
-                            f"Title: {title}",
-                            f"Folder: {folder_name}",
-                            f"Path: {relative_path}",
-                        ],
-                    ),
-                    ("CONTENT", [content]),
-                ]
-                document_string = build_document_metadata_string(metadata_sections)
-
-                summary_content = ""
-                if long_context_llm and enable_summary:
-                    doc_meta = {
-                        "folder_name": folder_name,
-                        "file_path": relative_path,
-                    }
-                    summary_content, _ = await generate_document_summary(
-                        document_string, long_context_llm, doc_meta
-                    )
-
-                embedding = embed_text(document_string)
-                chunks = await create_document_chunks(document_string)
-
-                parent_dir = str(Path(relative_path).parent)
-                if parent_dir == ".":
-                    parent_dir = ""
-                folder_id = folder_mapping.get(parent_dir, folder_mapping.get(""))
-
-                document.title = title
-                document.content = document_string
-                document.content_hash = content_hash
-                document.source_markdown = content
-                document.embedding = embedding
-                document.document_metadata = {
-                    "folder_name": folder_name,
-                    "file_path": relative_path,
-                    "summary": summary_content,
-                    "mtime": file_info["modified_at"].timestamp(),
-                }
-                document.folder_id = folder_id
-                await safe_set_chunks(session, document, chunks)
-                document.updated_at = get_current_timestamp()
-                document.status = DocumentStatus.ready()
-
-                indexed_count += 1
-
-                if indexed_count % 10 == 0:
-                    await session.commit()
-
-            except Exception as e:
-                logger.exception(f"Phase 2 error for {item.get('relative_path')}: {e}")
-                try:
-                    await session.rollback()
-                except Exception:
-                    pass
-                try:
-                    document.status = DocumentStatus.failed(str(e)[:500])
-                    document.updated_at = get_current_timestamp()
-                    await session.commit()
-                except Exception:
-                    try:
-                        await session.rollback()
-                    except Exception:
-                        pass
-                failed_count += 1
 
         # Cleanup empty folders
         existing_dirs = set()
@@ -846,8 +778,6 @@ async def index_local_folder(
                 raise
 
         warning_parts = []
-        if duplicate_count > 0:
-            warning_parts.append(f"{duplicate_count} duplicate")
         if failed_count > 0:
             warning_parts.append(f"{failed_count} failed")
         warning_message = ", ".join(warning_parts) if warning_parts else None
@@ -859,7 +789,6 @@ async def index_local_folder(
                 "indexed": indexed_count,
                 "skipped": skipped_count,
                 "failed": failed_count,
-                "duplicates": duplicate_count,
             },
         )
 
@@ -899,8 +828,8 @@ async def _index_single_file(
         if not full_path.exists():
             rel = str(full_path.relative_to(folder_path))
             unique_id = f"{folder_name}:{rel}"
-            uid_hash = generate_unique_identifier_hash(
-                DocumentType.LOCAL_FOLDER_FILE, unique_id, search_space_id
+            uid_hash = compute_identifier_hash(
+                DocumentType.LOCAL_FOLDER_FILE.value, unique_id, search_space_id
             )
             existing = await check_document_by_unique_identifier(session, uid_hash)
             if existing:
@@ -918,8 +847,8 @@ async def _index_single_file(
         rel_path = str(full_path.relative_to(folder_path))
 
         unique_id = f"{folder_name}:{rel_path}"
-        uid_hash = generate_unique_identifier_hash(
-            DocumentType.LOCAL_FOLDER_FILE, unique_id, search_space_id
+        uid_hash = compute_identifier_hash(
+            DocumentType.LOCAL_FOLDER_FILE.value, unique_id, search_space_id
         )
 
         try:
@@ -945,83 +874,51 @@ async def _index_single_file(
 
             await create_version_snapshot(session, existing)
 
-        long_context_llm = await get_user_long_context_llm(
-            session, user_id, search_space_id
-        )
-
-        title = full_path.name
         mtime = full_path.stat().st_mtime
 
-        metadata_sections = [
-            ("METADATA", [f"Title: {title}", f"Folder: {folder_name}", f"Path: {rel_path}"]),
-            ("CONTENT", [content]),
-        ]
-        document_string = build_document_metadata_string(metadata_sections)
+        connector_doc = _build_connector_doc(
+            title=full_path.name,
+            content=content,
+            relative_path=rel_path,
+            folder_name=folder_name,
+            search_space_id=search_space_id,
+            user_id=user_id,
+            enable_summary=enable_summary,
+        )
 
-        summary_content = ""
-        if long_context_llm and enable_summary:
-            summary_content, _ = await generate_document_summary(
-                document_string, long_context_llm, {"folder_name": folder_name, "file_path": rel_path}
-            )
+        pipeline = IndexingPipelineService(session)
+        llm = await get_user_long_context_llm(session, user_id, search_space_id)
+        documents = await pipeline.prepare_for_indexing([connector_doc])
 
-        embedding = embed_text(document_string)
-        chunks = await create_document_chunks(document_string)
+        if not documents:
+            return 0, 1, None
 
-        doc_metadata = {
-            "folder_name": folder_name,
-            "file_path": rel_path,
-            "summary": summary_content,
-            "mtime": mtime,
-        }
+        db_doc = documents[0]
+        await pipeline.index(db_doc, connector_doc, llm)
 
+        # Post-pipeline: assign folder_id and mtime
+        await session.refresh(db_doc)
         folder_id = None
         if root_folder_id:
             folder_id = await _resolve_folder_for_file(
                 session, rel_path, root_folder_id, search_space_id, user_id
             )
-
-        if existing:
-            existing.title = title
-            existing.content = document_string
-            existing.content_hash = content_hash
-            existing.source_markdown = content
-            existing.embedding = embedding
-            existing.document_metadata = doc_metadata
-            existing.folder_id = folder_id
-            await safe_set_chunks(session, existing, chunks)
-            existing.updated_at = get_current_timestamp()
-            existing.status = DocumentStatus.ready()
-        else:
-            document = Document(
-                search_space_id=search_space_id,
-                title=title,
-                document_type=DocumentType.LOCAL_FOLDER_FILE,
-                document_metadata=doc_metadata,
-                content=document_string,
-                content_hash=content_hash,
-                unique_identifier_hash=uid_hash,
-                source_markdown=content,
-                embedding=embedding,
-                status=DocumentStatus.ready(),
-                updated_at=get_current_timestamp(),
-                created_by_id=user_id,
-                connector_id=None,
-                folder_id=folder_id,
-            )
-            session.add(document)
-            await session.flush()
-            for chunk in chunks:
-                chunk.document_id = document.id
-            session.add_all(chunks)
-
+        db_doc.folder_id = folder_id
+        doc_meta = dict(db_doc.document_metadata or {})
+        doc_meta["mtime"] = mtime
+        db_doc.document_metadata = doc_meta
         await session.commit()
 
-        await task_logger.log_task_success(
-            log_entry,
-            f"Single file indexed: {rel_path}",
-            {"file": rel_path},
-        )
-        return 1, 0, None
+        indexed = 1 if DocumentStatus.is_state(db_doc.status, DocumentStatus.READY) else 0
+        failed_msg = None if indexed else "Indexing failed"
+
+        if indexed:
+            await task_logger.log_task_success(
+                log_entry,
+                f"Single file indexed: {rel_path}",
+                {"file": rel_path},
+            )
+        return indexed, 0 if indexed else 1, failed_msg
 
     except Exception as e:
         logger.exception(f"Error indexing single file {target_file_path}: {e}")
diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index 110aa6caf..154cc6e0e 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -1,8 +1,7 @@
-"""Integration tests for local folder indexer — Tier 3 (I1-I5), Tier 4 (F1-F5), Tier 5 (P1)."""
+"""Integration tests for local folder indexer — Tier 3 (I1-I5), Tier 4 (F1-F7), Tier 5 (P1)."""
 
 import os
 from pathlib import Path
-from unittest.mock import AsyncMock, MagicMock
 
 import pytest
 from sqlalchemy import func, select
@@ -18,41 +17,11 @@ from app.db import (
     User,
 )
 
-import app.tasks.connector_indexers.local_folder_indexer as _lfi_mod
-
 pytestmark = pytest.mark.integration
 
-
-@pytest.fixture
-def patched_self_hosted(monkeypatch):
-    _cfg = type("_Cfg", (), {"is_self_hosted": staticmethod(lambda: True)})()
-    monkeypatch.setattr(_lfi_mod, "config", _cfg)
-
-
-@pytest.fixture
-def patched_embed_for_indexer(monkeypatch):
-    from app.config import config as app_config
-    dim = app_config.embedding_model_instance.dimension
-    mock = MagicMock(return_value=[0.1] * dim)
-    monkeypatch.setattr(_lfi_mod, "embed_text", mock)
-    return mock
-
-
-@pytest.fixture
-def patched_chunks_for_indexer(monkeypatch):
-    from app.db import Chunk
-    from app.config import config as app_config
-    dim = app_config.embedding_model_instance.dimension
-
-    async def mock_create_chunks(text):
-        return [Chunk(content="chunk", embedding=[0.1] * dim)]
-
-    monkeypatch.setattr(_lfi_mod, "create_document_chunks", mock_create_chunks)
-
-
-@pytest.fixture
-def patched_summary_for_indexer(monkeypatch):
-    monkeypatch.setattr(_lfi_mod, "get_user_long_context_llm", AsyncMock(return_value=None))
+UNIFIED_FIXTURES = (
+    "patched_summarize", "patched_embed_texts", "patched_chunk_text",
+)
 
 
 # ====================================================================
@@ -62,12 +31,7 @@ def patched_summary_for_indexer(monkeypatch):
 
 class TestFullIndexer:
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_i1_new_file_indexed(
         self,
         db_session: AsyncSession,
@@ -103,12 +67,7 @@ class TestFullIndexer:
         assert docs[0].document_type == DocumentType.LOCAL_FOLDER_FILE
         assert DocumentStatus.is_state(docs[0].status, DocumentStatus.READY)
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_i2_unchanged_skipped(
         self,
         db_session: AsyncSession,
@@ -130,7 +89,6 @@ class TestFullIndexer:
         )
         assert count1 == 1
 
-        # Second run — unchanged, pass root_folder_id from first run
         count2, _, _, _ = await index_local_folder(
             session=db_session,
             search_space_id=db_search_space.id,
@@ -151,12 +109,7 @@ class TestFullIndexer:
         ).scalar_one()
         assert total == 1
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_i3_changed_reindexed(
         self,
         db_session: AsyncSession,
@@ -178,9 +131,7 @@ class TestFullIndexer:
             folder_name="test-folder",
         )
 
-        # Modify
         f.write_text("# Version 2\n\nUpdated.")
-        # Touch mtime to ensure it's detected as different
         os.utime(f, (f.stat().st_atime + 10, f.stat().st_mtime + 10))
 
         count, _, _, _ = await index_local_folder(
@@ -193,7 +144,6 @@ class TestFullIndexer:
         )
         assert count == 1
 
-        # Should have a version snapshot
         versions = (
             await db_session.execute(
                 select(DocumentVersion).join(Document).where(
@@ -204,12 +154,7 @@ class TestFullIndexer:
         ).scalars().all()
         assert len(versions) >= 1
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_i4_deleted_removed(
         self,
         db_session: AsyncSession,
@@ -262,12 +207,7 @@ class TestFullIndexer:
         ).scalar_one()
         assert docs_after == 0
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_i5_single_file_mode(
         self,
         db_session: AsyncSession,
@@ -305,18 +245,13 @@ class TestFullIndexer:
 
 
 # ====================================================================
-# Tier 4: Folder Mirroring (F1-F5)
+# Tier 4: Folder Mirroring (F1-F7)
 # ====================================================================
 
 
 class TestFolderMirroring:
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_f1_root_folder_created(
         self,
         db_session: AsyncSession,
@@ -344,12 +279,7 @@ class TestFolderMirroring:
         ).scalar_one()
         assert root_folder.name == "test-folder"
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_f2_nested_folder_rows(
         self,
         db_session: AsyncSession,
@@ -393,12 +323,7 @@ class TestFolderMirroring:
         assert daily_folder.parent_id == notes_folder.id
         assert weekly_folder.parent_id == notes_folder.id
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_f3_resync_reuses_folders(
         self,
         db_session: AsyncSession,
@@ -428,7 +353,6 @@ class TestFolderMirroring:
         ).scalars().all()
         ids_before = {f.id for f in folders_before}
 
-        # Re-sync with root_folder_id from first run
         await index_local_folder(
             session=db_session,
             search_space_id=db_search_space.id,
@@ -447,12 +371,7 @@ class TestFolderMirroring:
 
         assert ids_before == ids_after
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_f4_folder_id_assigned(
         self,
         db_session: AsyncSession,
@@ -496,15 +415,9 @@ class TestFolderMirroring:
 
         assert today_doc.folder_id == daily_folder.id
 
-        # Root doc should be in the root folder
         assert root_doc.folder_id == root_folder_id
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_f5_empty_folder_cleanup(
         self,
         db_session: AsyncSession,
@@ -531,7 +444,6 @@ class TestFolderMirroring:
             folder_name="test-folder",
         )
 
-        # Verify weekly folder exists
         weekly_folder = (
             await db_session.execute(
                 select(Folder).where(Folder.name == "weekly")
@@ -539,7 +451,6 @@ class TestFolderMirroring:
         ).scalar_one_or_none()
         assert weekly_folder is not None
 
-        # Delete weekly directory + its file
         shutil.rmtree(weekly)
 
         await index_local_folder(
@@ -551,7 +462,6 @@ class TestFolderMirroring:
             root_folder_id=root_folder_id,
         )
 
-        # weekly Folder should be gone (empty, dir removed)
         weekly_after = (
             await db_session.execute(
                 select(Folder).where(Folder.name == "weekly")
@@ -559,7 +469,6 @@ class TestFolderMirroring:
         ).scalar_one_or_none()
         assert weekly_after is None
 
-        # daily should still exist
         daily_after = (
             await db_session.execute(
                 select(Folder).where(Folder.name == "daily")
@@ -567,12 +476,7 @@ class TestFolderMirroring:
         ).scalar_one_or_none()
         assert daily_after is not None
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_f6_single_file_creates_subfolder(
         self,
         db_session: AsyncSession,
@@ -634,12 +538,7 @@ class TestFolderMirroring:
         assert daily_folder.parent_id == notes_folder.id
         assert notes_folder.parent_id == root_folder_id
 
-    @pytest.mark.usefixtures(
-        "patched_self_hosted",
-        "patched_embed_for_indexer",
-        "patched_chunks_for_indexer",
-        "patched_summary_for_indexer",
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_f7_single_file_delete_cleans_empty_folders(
         self,
         db_session: AsyncSession,
@@ -705,9 +604,7 @@ class TestFolderMirroring:
 
 class TestPipelineIntegration:
 
-    @pytest.mark.usefixtures(
-        "patched_summarize", "patched_embed_texts", "patched_chunk_text"
-    )
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_p1_local_folder_file_through_pipeline(
         self,
         db_session: AsyncSession,

From 25358fddcf17ff41c2f02a534bf0218eef96701f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Thu, 2 Apr 2026 23:46:21 +0530
Subject: [PATCH 31/70] feat: implement local folder synchronization and
 versioning with new metadata handling and document_versions table

---
 ...7_add_local_folder_sync_and_versioning.py} | 25 +++++-
 surfsense_backend/app/db.py                   |  1 +
 .../app/routes/documents_routes.py            | 42 ++++++++++
 .../app/routes/folders_routes.py              | 27 +++++++
 surfsense_backend/app/schemas/folders.py      |  3 +
 .../components/documents/FolderNode.tsx       | 24 ++++--
 .../components/documents/FolderTreeView.tsx   | 11 ++-
 .../layout/ui/sidebar/DocumentsSidebar.tsx    | 79 +++++++++++++++++--
 surfsense_web/contracts/types/folder.types.ts |  1 +
 .../lib/apis/documents-api.service.ts         |  5 ++
 surfsense_web/lib/apis/folders-api.service.ts |  4 +
 11 files changed, 205 insertions(+), 17 deletions(-)
 rename surfsense_backend/alembic/versions/{117_add_local_folder_connector_and_versioning.py => 117_add_local_folder_sync_and_versioning.py} (82%)

diff --git a/surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py b/surfsense_backend/alembic/versions/117_add_local_folder_sync_and_versioning.py
similarity index 82%
rename from surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py
rename to surfsense_backend/alembic/versions/117_add_local_folder_sync_and_versioning.py
index a9da3beb4..e322a608d 100644
--- a/surfsense_backend/alembic/versions/117_add_local_folder_connector_and_versioning.py
+++ b/surfsense_backend/alembic/versions/117_add_local_folder_sync_and_versioning.py
@@ -1,4 +1,4 @@
-"""Add LOCAL_FOLDER_FILE document type and document_versions table
+"""Add LOCAL_FOLDER_FILE document type, folder metadata, and document_versions table
 
 Revision ID: 117
 Revises: 116
@@ -38,6 +38,19 @@ def upgrade() -> None:
     """
     )
 
+    # Add JSONB metadata column to folders table
+    col_exists = conn.execute(
+        sa.text(
+            "SELECT 1 FROM information_schema.columns "
+            "WHERE table_name = 'folders' AND column_name = 'metadata'"
+        )
+    ).fetchone()
+    if not col_exists:
+        op.add_column(
+            "folders",
+            sa.Column("metadata", sa.dialects.postgresql.JSONB, nullable=True),
+        )
+
     # Create document_versions table
     table_exists = conn.execute(
         sa.text(
@@ -124,3 +137,13 @@ def downgrade() -> None:
     op.execute("DROP INDEX IF EXISTS ix_document_versions_created_at")
     op.execute("DROP INDEX IF EXISTS ix_document_versions_document_id")
     op.execute("DROP TABLE IF EXISTS document_versions")
+
+    # Drop metadata column from folders
+    col_exists = conn.execute(
+        sa.text(
+            "SELECT 1 FROM information_schema.columns "
+            "WHERE table_name = 'folders' AND column_name = 'metadata'"
+        )
+    ).fetchone()
+    if col_exists:
+        op.drop_column("folders", "metadata")
diff --git a/surfsense_backend/app/db.py b/surfsense_backend/app/db.py
index 1a4d3ea06..077b7daa6 100644
--- a/surfsense_backend/app/db.py
+++ b/surfsense_backend/app/db.py
@@ -956,6 +956,7 @@ class Folder(BaseModel, TimestampMixin):
         onupdate=lambda: datetime.now(UTC),
         index=True,
     )
+    folder_metadata = Column("metadata", JSONB, nullable=True)
 
     parent = relationship("Folder", remote_side="Folder.id", backref="children")
     search_space = relationship("SearchSpace", back_populates="folders")
diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index 05221b192..81bbb1477 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -1310,6 +1310,13 @@ async def folder_index(
         "You don't have permission to create documents in this search space",
     )
 
+    watched_metadata = {
+        "watched": True,
+        "folder_path": request.folder_path,
+        "exclude_patterns": request.exclude_patterns,
+        "file_extensions": request.file_extensions,
+    }
+
     root_folder_id = request.root_folder_id
     if root_folder_id:
         existing = (
@@ -1319,6 +1326,9 @@ async def folder_index(
         ).scalar_one_or_none()
         if not existing:
             root_folder_id = None
+        else:
+            existing.folder_metadata = watched_metadata
+            await session.commit()
 
     if not root_folder_id:
         root_folder = Folder(
@@ -1326,6 +1336,7 @@ async def folder_index(
             search_space_id=request.search_space_id,
             created_by_id=str(user.id),
             position="a0",
+            folder_metadata=watched_metadata,
         )
         session.add(root_folder)
         await session.flush()
@@ -1403,3 +1414,34 @@ async def folder_index_file(
         "message": "File indexing started",
         "status": "processing",
     }
+
+
+@router.get("/documents/watched-folders", response_model=list["FolderRead"])
+async def get_watched_folders(
+    search_space_id: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Return root folders that are marked as watched (metadata->>'watched' = 'true')."""
+    from app.schemas import FolderRead  # noqa: F811
+
+    await check_permission(
+        session,
+        user,
+        search_space_id,
+        Permission.DOCUMENTS_READ.value,
+        "You don't have permission to read documents in this search space",
+    )
+
+    folders = (
+        await session.execute(
+            select(Folder).where(
+                Folder.search_space_id == search_space_id,
+                Folder.parent_id.is_(None),
+                Folder.folder_metadata.isnot(None),
+                Folder.folder_metadata["watched"].astext == "true",
+            )
+        )
+    ).scalars().all()
+
+    return folders
diff --git a/surfsense_backend/app/routes/folders_routes.py b/surfsense_backend/app/routes/folders_routes.py
index d688e692a..6e524d4a4 100644
--- a/surfsense_backend/app/routes/folders_routes.py
+++ b/surfsense_backend/app/routes/folders_routes.py
@@ -192,6 +192,33 @@ async def get_folder_breadcrumb(
         ) from e
 
 
+@router.patch("/folders/{folder_id}/watched")
+async def stop_watching_folder(
+    folder_id: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Clear the watched flag from a folder's metadata."""
+    folder = await session.get(Folder, folder_id)
+    if not folder:
+        raise HTTPException(status_code=404, detail="Folder not found")
+
+    await check_permission(
+        session,
+        user,
+        folder.search_space_id,
+        Permission.DOCUMENTS_UPDATE.value,
+        "You don't have permission to update folders in this search space",
+    )
+
+    if folder.folder_metadata and isinstance(folder.folder_metadata, dict):
+        updated = {**folder.folder_metadata, "watched": False}
+        folder.folder_metadata = updated
+    await session.commit()
+
+    return {"message": "Folder watch status updated"}
+
+
 @router.put("/folders/{folder_id}", response_model=FolderRead)
 async def update_folder(
     folder_id: int,
diff --git a/surfsense_backend/app/schemas/folders.py b/surfsense_backend/app/schemas/folders.py
index 263817182..e8bdf3821 100644
--- a/surfsense_backend/app/schemas/folders.py
+++ b/surfsense_backend/app/schemas/folders.py
@@ -3,6 +3,8 @@
 from datetime import datetime
 from uuid import UUID
 
+from typing import Any
+
 from pydantic import BaseModel, ConfigDict, Field
 
 
@@ -34,6 +36,7 @@ class FolderRead(BaseModel):
     created_by_id: UUID | None
     created_at: datetime
     updated_at: datetime
+    metadata: dict[str, Any] | None = Field(default=None, validation_alias="folder_metadata")
 
     model_config = ConfigDict(from_attributes=True)
 
diff --git a/surfsense_web/components/documents/FolderNode.tsx b/surfsense_web/components/documents/FolderNode.tsx
index 1521c06fe..6780bd1e5 100644
--- a/surfsense_web/components/documents/FolderNode.tsx
+++ b/surfsense_web/components/documents/FolderNode.tsx
@@ -76,6 +76,7 @@ interface FolderNodeProps {
 	isWatched?: boolean;
 	onRescan?: (folder: FolderDisplay) => void;
 	onStopWatching?: (folder: FolderDisplay) => void;
+	onViewMetadata?: (folder: FolderDisplay) => void;
 }
 
 function getDropZone(
@@ -116,6 +117,7 @@ export const FolderNode = React.memo(function FolderNode({
 	isWatched,
 	onRescan,
 	onStopWatching,
+	onViewMetadata,
 }: FolderNodeProps) {
 	const [renameValue, setRenameValue] = useState(folder.name);
 	const inputRef = useRef<HTMLInputElement>(null);
@@ -251,13 +253,21 @@ export const FolderNode = React.memo(function FolderNode({
 						isOver && !canDrop && "cursor-not-allowed"
 					)}
 					style={{ paddingLeft: `${depth * 16 + 4}px` }}
-					onClick={() => onToggleExpand(folder.id)}
-					onKeyDown={(e) => {
-						if (e.key === "Enter" || e.key === " ") {
-							e.preventDefault();
-							onToggleExpand(folder.id);
-						}
-					}}
+				onClick={(e) => {
+					if ((e.ctrlKey || e.metaKey) && onViewMetadata) {
+						e.preventDefault();
+						e.stopPropagation();
+						onViewMetadata(folder);
+						return;
+					}
+					onToggleExpand(folder.id);
+				}}
+				onKeyDown={(e) => {
+					if (e.key === "Enter" || e.key === " ") {
+						e.preventDefault();
+						onToggleExpand(folder.id);
+					}
+				}}
 					onDoubleClick={(e) => {
 						e.stopPropagation();
 						startRename();
diff --git a/surfsense_web/components/documents/FolderTreeView.tsx b/surfsense_web/components/documents/FolderTreeView.tsx
index 5945edccb..f34b9a0c2 100644
--- a/surfsense_web/components/documents/FolderTreeView.tsx
+++ b/surfsense_web/components/documents/FolderTreeView.tsx
@@ -43,6 +43,7 @@ interface FolderTreeViewProps {
 	watchedFolderIds?: Set<number>;
 	onRescanFolder?: (folder: FolderDisplay) => void;
 	onStopWatchingFolder?: (folder: FolderDisplay) => void;
+	onViewFolderMetadata?: (folder: FolderDisplay) => void;
 }
 
 function groupBy<T>(items: T[], keyFn: (item: T) => string | number): Record<string | number, T[]> {
@@ -79,6 +80,7 @@ export function FolderTreeView({
 	watchedFolderIds,
 	onRescanFolder,
 	onStopWatchingFolder,
+	onViewFolderMetadata,
 }: FolderTreeViewProps) {
 	const foldersByParent = useMemo(() => groupBy(folders, (f) => f.parentId ?? "root"), [folders]);
 
@@ -210,10 +212,11 @@ export function FolderTreeView({
 					siblingPositions={siblingPositions}
 					contextMenuOpen={openContextMenuId === `folder-${f.id}`}
 					onContextMenuOpenChange={(open) => setOpenContextMenuId(open ? `folder-${f.id}` : null)}
-					isWatched={watchedFolderIds?.has(f.id)}
-					onRescan={onRescanFolder}
-					onStopWatching={onStopWatchingFolder}
-				/>
+				isWatched={watchedFolderIds?.has(f.id)}
+				onRescan={onRescanFolder}
+				onStopWatching={onStopWatchingFolder}
+				onViewMetadata={onViewFolderMetadata}
+			/>
 			);
 
 			if (isExpanded) {
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index 202d170d9..f9d32bf98 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -21,6 +21,7 @@ import type { DocumentNodeDoc } from "@/components/documents/DocumentNode";
 import type { FolderDisplay } from "@/components/documents/FolderNode";
 import { FolderPickerDialog } from "@/components/documents/FolderPickerDialog";
 import { FolderTreeView } from "@/components/documents/FolderTreeView";
+import { JsonMetadataViewer } from "@/components/json-metadata-viewer";
 import { EXPORT_FILE_EXTENSIONS } from "@/components/shared/ExportMenuItems";
 import {
 	AlertDialog,
@@ -95,12 +96,46 @@ export function DocumentsSidebar({
 	const [activeTypes, setActiveTypes] = useState<DocumentTypeEnum[]>([]);
 	const [watchedFolderIds, setWatchedFolderIds] = useState<Set<number>>(new Set());
 
+	const [metadataFolder, setMetadataFolder] = useState<FolderDisplay | null>(null);
+	const [metadataJson, setMetadataJson] = useState<Record<string, unknown> | null>(null);
+	const [metadataLoading, setMetadataLoading] = useState(false);
+
 	useEffect(() => {
 		const api = typeof window !== "undefined" ? window.electronAPI : null;
 		if (!api?.getWatchedFolders) return;
 
 		async function loadWatchedIds() {
 			const folders = await api!.getWatchedFolders();
+
+			if (folders.length === 0) {
+				try {
+					const backendFolders = await documentsApiService.getWatchedFolders(searchSpaceId);
+					for (const bf of backendFolders) {
+						const meta = bf.metadata as Record<string, unknown> | null;
+						if (!meta?.watched || !meta.folder_path) continue;
+						await api!.addWatchedFolder({
+							path: meta.folder_path as string,
+							name: bf.name,
+							rootFolderId: bf.id,
+							searchSpaceId: bf.search_space_id,
+							excludePatterns: (meta.exclude_patterns as string[]) ?? [],
+							fileExtensions: (meta.file_extensions as string[] | null) ?? null,
+							active: true,
+						});
+					}
+					const recovered = await api!.getWatchedFolders();
+					const ids = new Set(
+						recovered
+							.filter((f) => f.rootFolderId != null)
+							.map((f) => f.rootFolderId as number)
+					);
+					setWatchedFolderIds(ids);
+					return;
+				} catch (err) {
+					console.error("[DocumentsSidebar] Recovery from backend failed:", err);
+				}
+			}
+
 			const ids = new Set(
 				folders
 					.filter((f) => f.rootFolderId != null)
@@ -110,7 +145,7 @@ export function DocumentsSidebar({
 		}
 
 		loadWatchedIds();
-	}, []);
+	}, [searchSpaceId]);
 	const { mutateAsync: deleteDocumentMutation } = useAtomValue(deleteDocumentMutationAtom);
 
 	const [sidebarDocs, setSidebarDocs] = useAtom(sidebarSelectedDocumentsAtom);
@@ -318,11 +353,30 @@ export function DocumentsSidebar({
 			}
 
 			await api.removeWatchedFolder(matched.path);
+			try {
+				await foldersApiService.stopWatching(folder.id);
+			} catch (err) {
+				console.error("[DocumentsSidebar] Failed to clear watched metadata:", err);
+			}
 			toast.success(`Stopped watching: ${matched.name}`);
 		},
 		[]
 	);
 
+	const handleViewFolderMetadata = useCallback(async (folder: FolderDisplay) => {
+		setMetadataFolder(folder);
+		setMetadataLoading(true);
+		try {
+			const fullFolder = await foldersApiService.getFolder(folder.id);
+			setMetadataJson((fullFolder.metadata as Record<string, unknown>) ?? {});
+		} catch (err) {
+			console.error("[DocumentsSidebar] Failed to fetch folder metadata:", err);
+			setMetadataJson({ error: "Failed to load folder metadata" });
+		} finally {
+			setMetadataLoading(false);
+		}
+	}, []);
+
 	const handleRenameFolder = useCallback(async (folder: FolderDisplay, newName: string) => {
 		try {
 			await foldersApiService.updateFolder(folder.id, { name: newName });
@@ -801,11 +855,26 @@ export function DocumentsSidebar({
 				onReorderFolder={handleReorderFolder}
 				watchedFolderIds={watchedFolderIds}
 				onRescanFolder={handleRescanFolder}
-				onStopWatchingFolder={handleStopWatching}
-			/>
-			</div>
+			onStopWatchingFolder={handleStopWatching}
+			onViewFolderMetadata={handleViewFolderMetadata}
+		/>
+		</div>
 
-			<FolderPickerDialog
+		<JsonMetadataViewer
+			title={metadataFolder?.name ?? "Folder"}
+			metadata={metadataJson}
+			loading={metadataLoading}
+			open={!!metadataFolder}
+			onOpenChange={(open) => {
+				if (!open) {
+					setMetadataFolder(null);
+					setMetadataJson(null);
+					setMetadataLoading(false);
+				}
+			}}
+		/>
+
+		<FolderPickerDialog
 				open={folderPickerOpen}
 				onOpenChange={setFolderPickerOpen}
 				folders={treeFolders}
diff --git a/surfsense_web/contracts/types/folder.types.ts b/surfsense_web/contracts/types/folder.types.ts
index d33a3ddd7..60919bf46 100644
--- a/surfsense_web/contracts/types/folder.types.ts
+++ b/surfsense_web/contracts/types/folder.types.ts
@@ -9,6 +9,7 @@ export const folder = z.object({
 	created_by_id: z.string().nullable().optional(),
 	created_at: z.string(),
 	updated_at: z.string(),
+	metadata: z.record(z.unknown()).nullable().optional(),
 });
 
 export const folderCreateRequest = z.object({
diff --git a/surfsense_web/lib/apis/documents-api.service.ts b/surfsense_web/lib/apis/documents-api.service.ts
index a8e3831d4..e8b228d03 100644
--- a/surfsense_web/lib/apis/documents-api.service.ts
+++ b/surfsense_web/lib/apis/documents-api.service.ts
@@ -37,6 +37,7 @@ import {
 	uploadDocumentRequest,
 	uploadDocumentResponse,
 } from "@/contracts/types/document.types";
+import { folderListResponse } from "@/contracts/types/folder.types";
 import { ValidationError } from "../error";
 import { baseApiService } from "./base-api.service";
 
@@ -403,6 +404,10 @@ class DocumentsApiService {
 		return baseApiService.post(`/api/v1/documents/folder-index-file`, undefined, { body });
 	};
 
+	getWatchedFolders = async (searchSpaceId: number) => {
+		return baseApiService.get(`/api/v1/documents/watched-folders?search_space_id=${searchSpaceId}`, folderListResponse);
+	};
+
 	/**
 	 * Delete a document
 	 */
diff --git a/surfsense_web/lib/apis/folders-api.service.ts b/surfsense_web/lib/apis/folders-api.service.ts
index 99d9ad774..2e535d615 100644
--- a/surfsense_web/lib/apis/folders-api.service.ts
+++ b/surfsense_web/lib/apis/folders-api.service.ts
@@ -85,6 +85,10 @@ class FoldersApiService {
 		return baseApiService.delete(`/api/v1/folders/${folderId}`, folderDeleteResponse);
 	};
 
+	stopWatching = async (folderId: number) => {
+		return baseApiService.patch(`/api/v1/folders/${folderId}/watched`, undefined);
+	};
+
 	moveDocument = async (documentId: number, request: DocumentMoveRequest) => {
 		const parsed = documentMoveRequest.safeParse(request);
 		if (!parsed.success) {

From f0a7c7134a7e81a8ee202e854afbfc98d9ad182a Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 00:09:17 +0530
Subject: [PATCH 32/70] feat: move endpoint above to retrieve watched folders
 based on search space ID

---
 .../app/routes/documents_routes.py            | 60 ++++++++++---------
 1 file changed, 31 insertions(+), 29 deletions(-)

diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index 81bbb1477..0acc1d30b 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -953,6 +953,37 @@ async def get_document_by_chunk_id(
         ) from e
 
 
+@router.get("/documents/watched-folders", response_model=list["FolderRead"])
+async def get_watched_folders(
+    search_space_id: int,
+    session: AsyncSession = Depends(get_async_session),
+    user: User = Depends(current_active_user),
+):
+    """Return root folders that are marked as watched (metadata->>'watched' = 'true')."""
+    from app.schemas import FolderRead  # noqa: F811
+
+    await check_permission(
+        session,
+        user,
+        search_space_id,
+        Permission.DOCUMENTS_READ.value,
+        "You don't have permission to read documents in this search space",
+    )
+
+    folders = (
+        await session.execute(
+            select(Folder).where(
+                Folder.search_space_id == search_space_id,
+                Folder.parent_id.is_(None),
+                Folder.folder_metadata.isnot(None),
+                Folder.folder_metadata["watched"].astext == "true",
+            )
+        )
+    ).scalars().all()
+
+    return folders
+
+
 @router.get("/documents/{document_id}", response_model=DocumentRead)
 async def read_document(
     document_id: int,
@@ -1416,32 +1447,3 @@ async def folder_index_file(
     }
 
 
-@router.get("/documents/watched-folders", response_model=list["FolderRead"])
-async def get_watched_folders(
-    search_space_id: int,
-    session: AsyncSession = Depends(get_async_session),
-    user: User = Depends(current_active_user),
-):
-    """Return root folders that are marked as watched (metadata->>'watched' = 'true')."""
-    from app.schemas import FolderRead  # noqa: F811
-
-    await check_permission(
-        session,
-        user,
-        search_space_id,
-        Permission.DOCUMENTS_READ.value,
-        "You don't have permission to read documents in this search space",
-    )
-
-    folders = (
-        await session.execute(
-            select(Folder).where(
-                Folder.search_space_id == search_space_id,
-                Folder.parent_id.is_(None),
-                Folder.folder_metadata.isnot(None),
-                Folder.folder_metadata["watched"].astext == "true",
-            )
-        )
-    ).scalars().all()
-
-    return folders

From b46c5532b3fb02c3fd7277021d128e4f2f8a3180 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 00:28:24 +0530
Subject: [PATCH 33/70] feat: add unified file and folder browsing
 functionality with IPC channel integration

---
 surfsense_desktop/src/ipc/channels.ts         |   2 +
 surfsense_desktop/src/ipc/handlers.ts         |   8 +
 .../src/modules/folder-watcher.ts             |  68 +++++
 surfsense_desktop/src/preload.ts              |   4 +
 .../(manage)/components/DocumentsFilters.tsx  |  23 +-
 .../layout/ui/sidebar/DocumentsSidebar.tsx    |  51 +---
 .../components/sources/DocumentUploadTab.tsx  | 284 ++++++++++++++----
 surfsense_web/types/window.d.ts               |  15 +
 8 files changed, 335 insertions(+), 120 deletions(-)

diff --git a/surfsense_desktop/src/ipc/channels.ts b/surfsense_desktop/src/ipc/channels.ts
index 66788d90e..19c26607d 100644
--- a/surfsense_desktop/src/ipc/channels.ts
+++ b/surfsense_desktop/src/ipc/channels.ts
@@ -17,4 +17,6 @@ export const IPC_CHANNELS = {
   FOLDER_SYNC_PAUSE: 'folder-sync:pause',
   FOLDER_SYNC_RESUME: 'folder-sync:resume',
   FOLDER_SYNC_RENDERER_READY: 'folder-sync:renderer-ready',
+  BROWSE_FILE_OR_FOLDER: 'browse:file-or-folder',
+  READ_LOCAL_FILES: 'browse:read-local-files',
 } as const;
diff --git a/surfsense_desktop/src/ipc/handlers.ts b/surfsense_desktop/src/ipc/handlers.ts
index 19051e871..246f0f6ac 100644
--- a/surfsense_desktop/src/ipc/handlers.ts
+++ b/surfsense_desktop/src/ipc/handlers.ts
@@ -9,6 +9,8 @@ import {
   pauseWatcher,
   resumeWatcher,
   markRendererReady,
+  browseFileOrFolder,
+  readLocalFiles,
 } from '../modules/folder-watcher';
 
 export function registerIpcHandlers(): void {
@@ -49,4 +51,10 @@ export function registerIpcHandlers(): void {
   ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_RENDERER_READY, () => {
     markRendererReady();
   });
+
+  ipcMain.handle(IPC_CHANNELS.BROWSE_FILE_OR_FOLDER, () => browseFileOrFolder());
+
+  ipcMain.handle(IPC_CHANNELS.READ_LOCAL_FILES, (_event, paths: string[]) =>
+    readLocalFiles(paths)
+  );
 }
diff --git a/surfsense_desktop/src/modules/folder-watcher.ts b/surfsense_desktop/src/modules/folder-watcher.ts
index 81a835c22..1324858a0 100644
--- a/surfsense_desktop/src/modules/folder-watcher.ts
+++ b/surfsense_desktop/src/modules/folder-watcher.ts
@@ -391,3 +391,71 @@ export async function unregisterFolderWatcher(): Promise<void> {
   }
   watchers.clear();
 }
+
+export interface BrowseResult {
+  type: 'files' | 'folder';
+  paths: string[];
+}
+
+export async function browseFileOrFolder(): Promise<BrowseResult | null> {
+  const result = await dialog.showOpenDialog({
+    properties: ['openFile', 'openDirectory', 'multiSelections'],
+    title: 'Select files or a folder',
+  });
+  if (result.canceled || result.filePaths.length === 0) return null;
+
+  const stat = fs.statSync(result.filePaths[0]);
+  if (stat.isDirectory()) {
+    return { type: 'folder', paths: [result.filePaths[0]] };
+  }
+  return { type: 'files', paths: result.filePaths };
+}
+
+const MIME_MAP: Record<string, string> = {
+  '.pdf': 'application/pdf',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  '.html': 'text/html', '.htm': 'text/html',
+  '.csv': 'text/csv',
+  '.txt': 'text/plain',
+  '.md': 'text/markdown', '.markdown': 'text/markdown',
+  '.mp3': 'audio/mpeg', '.mpeg': 'audio/mpeg', '.mpga': 'audio/mpeg',
+  '.mp4': 'audio/mp4', '.m4a': 'audio/mp4',
+  '.wav': 'audio/wav',
+  '.webm': 'audio/webm',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.bmp': 'image/bmp',
+  '.webp': 'image/webp',
+  '.tiff': 'image/tiff',
+  '.doc': 'application/msword',
+  '.rtf': 'application/rtf',
+  '.xml': 'application/xml',
+  '.epub': 'application/epub+zip',
+  '.xls': 'application/vnd.ms-excel',
+  '.ppt': 'application/vnd.ms-powerpoint',
+  '.eml': 'message/rfc822',
+  '.odt': 'application/vnd.oasis.opendocument.text',
+  '.msg': 'application/vnd.ms-outlook',
+};
+
+export interface LocalFileData {
+  name: string;
+  data: ArrayBuffer;
+  mimeType: string;
+  size: number;
+}
+
+export function readLocalFiles(filePaths: string[]): LocalFileData[] {
+  return filePaths.map((p) => {
+    const buf = fs.readFileSync(p);
+    const ext = path.extname(p).toLowerCase();
+    return {
+      name: path.basename(p),
+      data: buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength),
+      mimeType: MIME_MAP[ext] || 'application/octet-stream',
+      size: buf.byteLength,
+    };
+  });
+}
diff --git a/surfsense_desktop/src/preload.ts b/surfsense_desktop/src/preload.ts
index 7c190db10..08ca87f8f 100644
--- a/surfsense_desktop/src/preload.ts
+++ b/surfsense_desktop/src/preload.ts
@@ -45,4 +45,8 @@ contextBridge.exposeInMainWorld('electronAPI', {
   pauseWatcher: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_PAUSE),
   resumeWatcher: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_RESUME),
   signalRendererReady: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_RENDERER_READY),
+
+  // Unified browse (files + folders)
+  browseFileOrFolder: () => ipcRenderer.invoke(IPC_CHANNELS.BROWSE_FILE_OR_FOLDER),
+  readLocalFiles: (paths: string[]) => ipcRenderer.invoke(IPC_CHANNELS.READ_LOCAL_FILES, paths),
 });
diff --git a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx
index fcd3a39da..150c119de 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Eye, FolderPlus, ListFilter, Search, Upload, X } from "lucide-react";
+import { FolderPlus, ListFilter, Search, Upload, X } from "lucide-react";
 import { useTranslations } from "next-intl";
 import React, { useCallback, useMemo, useRef, useState } from "react";
 import { useDocumentUploadDialog } from "@/components/assistant-ui/document-upload-popup";
@@ -19,7 +19,6 @@ export function DocumentsFilters({
 	onToggleType,
 	activeTypes,
 	onCreateFolder,
-	onWatchFolder,
 }: {
 	typeCounts: Partial<Record<DocumentTypeEnum, number>>;
 	onSearch: (v: string) => void;
@@ -27,7 +26,6 @@ export function DocumentsFilters({
 	onToggleType: (type: DocumentTypeEnum, checked: boolean) => void;
 	activeTypes: DocumentTypeEnum[];
 	onCreateFolder?: () => void;
-	onWatchFolder?: () => void;
 }) {
 	const t = useTranslations("documents");
 	const id = React.useId();
@@ -216,24 +214,7 @@ export function DocumentsFilters({
 					</Tooltip>
 				)}
 
-			{/* Watch Folder Button (desktop only) */}
-			{onWatchFolder && (
-				<Tooltip>
-					<TooltipTrigger asChild>
-						<Button
-							variant="outline"
-							size="icon"
-							className="h-9 w-9 shrink-0 border-dashed border-sidebar-border text-sidebar-foreground/60 hover:text-sidebar-foreground hover:border-sidebar-border bg-sidebar"
-							onClick={onWatchFolder}
-						>
-							<Eye size={14} />
-						</Button>
-					</TooltipTrigger>
-					<TooltipContent>Watch folder</TooltipContent>
-				</Tooltip>
-			)}
-
-			{/* Upload Button */}
+		{/* Upload Button */}
 			<Button
 				data-joyride="upload-button"
 				onClick={openUploadDialog}
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index f9d32bf98..ed3a78786 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -279,40 +279,6 @@ export function DocumentsSidebar({
 
 	const isElectron = typeof window !== "undefined" && !!window.electronAPI;
 
-	const handleWatchFolder = useCallback(async () => {
-		const api = window.electronAPI;
-		if (!api) return;
-
-		const folderPath = await api.selectFolder();
-		if (!folderPath) return;
-
-		const folderName = folderPath.split("/").pop() || folderPath.split("\\").pop() || folderPath;
-
-		try {
-			const result = await documentsApiService.folderIndex(searchSpaceId, {
-				folder_path: folderPath,
-				folder_name: folderName,
-				search_space_id: searchSpaceId,
-			});
-
-			const rootFolderId = (result as { root_folder_id?: number })?.root_folder_id ?? null;
-
-			await api.addWatchedFolder({
-				path: folderPath,
-				name: folderName,
-				excludePatterns: [".git", "node_modules", "__pycache__", ".DS_Store", ".obsidian", ".trash"],
-				fileExtensions: null,
-				rootFolderId,
-				searchSpaceId,
-				active: true,
-			});
-
-			toast.success(`Watching folder: ${folderName}`);
-		} catch (err) {
-			toast.error((err as Error)?.message || "Failed to watch folder");
-		}
-	}, [searchSpaceId]);
-
 	const handleRescanFolder = useCallback(
 		async (folder: FolderDisplay) => {
 			const api = window.electronAPI;
@@ -795,15 +761,14 @@ export function DocumentsSidebar({
 
 			<div className="flex-1 min-h-0 overflow-x-hidden pt-0 flex flex-col">
 				<div className="px-4 pb-2">
-				<DocumentsFilters
-					typeCounts={typeCounts}
-					onSearch={setSearch}
-					searchValue={search}
-					onToggleType={onToggleType}
-					activeTypes={activeTypes}
-					onCreateFolder={() => handleCreateFolder(null)}
-					onWatchFolder={isElectron ? handleWatchFolder : undefined}
-				/>
+			<DocumentsFilters
+				typeCounts={typeCounts}
+				onSearch={setSearch}
+				searchValue={search}
+				onToggleType={onToggleType}
+				activeTypes={activeTypes}
+				onCreateFolder={() => handleCreateFolder(null)}
+			/>
 				</div>
 
 				{deletableSelectedIds.length > 0 && (
diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index 6817b19db..3fdf576b5 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAtom } from "jotai";
-import { CheckCircle2, FileType, Info, Upload, X } from "lucide-react";
+import { CheckCircle2, FileType, FolderOpen, Info, Upload, X } from "lucide-react";
 
 import { useTranslations } from "next-intl";
 import { useCallback, useMemo, useRef, useState } from "react";
@@ -19,9 +19,12 @@ import { Alert, AlertDescription } from "@/components/ui/alert";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Label } from "@/components/ui/label";
 import { Progress } from "@/components/ui/progress";
 import { Separator } from "@/components/ui/separator";
 import { Spinner } from "@/components/ui/spinner";
+import { Switch } from "@/components/ui/switch";
+import { documentsApiService } from "@/lib/apis/documents-api.service";
 import {
 	trackDocumentUploadFailure,
 	trackDocumentUploadStarted,
@@ -29,6 +32,11 @@ import {
 } from "@/lib/posthog/events";
 import { GridPattern } from "./GridPattern";
 
+interface SelectedFolder {
+	path: string;
+	name: string;
+}
+
 interface DocumentUploadTabProps {
 	searchSpaceId: string;
 	onSuccess?: () => void;
@@ -135,6 +143,11 @@ export function DocumentUploadTab({
 	const { mutate: uploadDocuments, isPending: isUploading } = uploadDocumentMutation;
 	const fileInputRef = useRef<HTMLInputElement>(null);
 
+	const [selectedFolder, setSelectedFolder] = useState<SelectedFolder | null>(null);
+	const [watchFolder, setWatchFolder] = useState(true);
+	const [folderSubmitting, setFolderSubmitting] = useState(false);
+	const isElectron = typeof window !== "undefined" && !!window.electronAPI?.browseFileOrFolder;
+
 	const acceptedFileTypes = useMemo(() => {
 		const etlService = process.env.NEXT_PUBLIC_ETL_SERVICE;
 		return FILE_TYPE_CONFIG[etlService || "default"] || FILE_TYPE_CONFIG.default;
@@ -147,6 +160,7 @@ export function DocumentUploadTab({
 
 	const onDrop = useCallback(
 		(acceptedFiles: File[]) => {
+			setSelectedFolder(null);
 			setFiles((prev) => {
 				const newEntries = acceptedFiles.map((f) => ({
 					id: crypto.randomUUID?.() ?? `file-${Date.now()}-${Math.random().toString(36)}`,
@@ -179,15 +193,60 @@ export function DocumentUploadTab({
 		onDrop,
 		accept: acceptedFileTypes,
 		maxSize: 50 * 1024 * 1024, // 50MB per file
-		noClick: false,
+		noClick: !isElectron,
 		disabled: files.length >= MAX_FILES,
 	});
 
-	// Handle file input click to prevent event bubbling that might reopen dialog
 	const handleFileInputClick = useCallback((e: React.MouseEvent<HTMLInputElement>) => {
 		e.stopPropagation();
 	}, []);
 
+	const handleBrowse = useCallback(async (e: React.MouseEvent) => {
+		e.stopPropagation();
+		e.preventDefault();
+
+		const api = window.electronAPI;
+		if (!api?.browseFileOrFolder) {
+			fileInputRef.current?.click();
+			return;
+		}
+
+		const result = await api.browseFileOrFolder();
+		if (!result) return;
+
+		if (result.type === "folder") {
+			const folderPath = result.paths[0];
+			const folderName = folderPath.split("/").pop() || folderPath.split("\\").pop() || folderPath;
+			setFiles([]);
+			setSelectedFolder({ path: folderPath, name: folderName });
+			setWatchFolder(true);
+		} else {
+			setSelectedFolder(null);
+			const fileDataList = await api.readLocalFiles(result.paths);
+			const newFiles: FileWithId[] = fileDataList.map((fd) => ({
+				id: crypto.randomUUID?.() ?? `file-${Date.now()}-${Math.random().toString(36)}`,
+				file: new File([fd.data], fd.name, { type: fd.mimeType }),
+			}));
+			setFiles((prev) => {
+				const merged = [...prev, ...newFiles];
+				if (merged.length > MAX_FILES) {
+					toast.error(t("max_files_exceeded"), {
+						description: t("max_files_exceeded_desc", { max: MAX_FILES }),
+					});
+					return prev;
+				}
+				const totalSize = merged.reduce((sum, e) => sum + e.file.size, 0);
+				if (totalSize > MAX_TOTAL_SIZE_BYTES) {
+					toast.error(t("max_size_exceeded"), {
+						description: t("max_size_exceeded_desc", { max: MAX_TOTAL_SIZE_MB }),
+					});
+					return prev;
+				}
+				return merged;
+			});
+		}
+	}, [t]);
+
 	const formatFileSize = (bytes: number) => {
 		if (bytes === 0) return "0 Bytes";
 		const k = 1024;
@@ -198,7 +257,6 @@ export function DocumentUploadTab({
 
 	const totalFileSize = files.reduce((total, entry) => total + entry.file.size, 0);
 
-	// Check if limits are reached
 	const isFileCountLimitReached = files.length >= MAX_FILES;
 	const isSizeLimitReached = totalFileSize >= MAX_TOTAL_SIZE_BYTES;
 	const remainingFiles = MAX_FILES - files.length;
@@ -207,7 +265,6 @@ export function DocumentUploadTab({
 		(MAX_TOTAL_SIZE_BYTES - totalFileSize) / (1024 * 1024)
 	).toFixed(1);
 
-	// Track accordion state changes
 	const handleAccordionChange = useCallback(
 		(value: string) => {
 			setAccordionValue(value);
@@ -216,6 +273,46 @@ export function DocumentUploadTab({
 		[onAccordionStateChange]
 	);
 
+	const handleFolderSubmit = useCallback(async () => {
+		if (!selectedFolder) return;
+		const api = window.electronAPI;
+		if (!api) return;
+
+		setFolderSubmitting(true);
+		try {
+			const result = await documentsApiService.folderIndex(Number(searchSpaceId), {
+				folder_path: selectedFolder.path,
+				folder_name: selectedFolder.name,
+				search_space_id: searchSpaceId,
+				enable_summary: shouldSummarize,
+			});
+
+			const rootFolderId = (result as { root_folder_id?: number })?.root_folder_id ?? null;
+
+			if (watchFolder) {
+				await api.addWatchedFolder({
+					path: selectedFolder.path,
+					name: selectedFolder.name,
+					excludePatterns: [".git", "node_modules", "__pycache__", ".DS_Store", ".obsidian", ".trash"],
+					fileExtensions: null,
+					rootFolderId,
+					searchSpaceId: Number(searchSpaceId),
+					active: true,
+				});
+				toast.success(`Watching folder: ${selectedFolder.name}`);
+			} else {
+				toast.success(`Indexing folder: ${selectedFolder.name}`);
+			}
+
+			setSelectedFolder(null);
+			onSuccess?.();
+		} catch (err) {
+			toast.error((err as Error)?.message || "Failed to process folder");
+		} finally {
+			setFolderSubmitting(false);
+		}
+	}, [selectedFolder, watchFolder, searchSpaceId, shouldSummarize, onSuccess]);
+
 	const handleUpload = async () => {
 		setUploadProgress(0);
 		trackDocumentUploadStarted(Number(searchSpaceId), files.length, totalFileSize);
@@ -262,58 +359,68 @@ export function DocumentUploadTab({
 				</AlertDescription>
 			</Alert>
 
-			<Card className={`relative overflow-hidden ${cardClass}`}>
-				<div className="absolute inset-0 [mask-image:radial-gradient(ellipse_at_center,white,transparent)] opacity-30">
-					<GridPattern />
-				</div>
-				<CardContent className="p-4 sm:p-10 relative z-10">
-					<div
-						{...getRootProps()}
-						className={`flex flex-col items-center justify-center min-h-[200px] sm:min-h-[300px] border-2 border-dashed rounded-lg transition-colors ${
-							isFileCountLimitReached || isSizeLimitReached
-								? "border-destructive/50 bg-destructive/5 cursor-not-allowed"
-								: "border-border hover:border-primary/50 cursor-pointer"
-						}`}
-					>
-						<input
-							{...getInputProps()}
-							ref={fileInputRef}
-							className="hidden"
-							onClick={handleFileInputClick}
-						/>
-						{isFileCountLimitReached ? (
-							<div className="flex flex-col items-center gap-2 sm:gap-4 text-center px-4">
-								<Upload className="h-8 w-8 sm:h-12 sm:w-12 text-destructive/70" />
-								<div>
-									<p className="text-sm sm:text-lg font-medium text-destructive">
-										{t("file_limit_reached")}
-									</p>
-									<p className="text-xs sm:text-sm text-muted-foreground mt-1">
-										{t("file_limit_reached_desc", { max: MAX_FILES })}
-									</p>
-								</div>
+		<Card className={`relative overflow-hidden ${cardClass}`}>
+			<div className="absolute inset-0 [mask-image:radial-gradient(ellipse_at_center,white,transparent)] opacity-30">
+				<GridPattern />
+			</div>
+			<CardContent className="p-4 sm:p-10 relative z-10">
+				<div
+					{...getRootProps()}
+					className={`flex flex-col items-center justify-center min-h-[200px] sm:min-h-[300px] border-2 border-dashed rounded-lg transition-colors ${
+						isFileCountLimitReached || isSizeLimitReached
+							? "border-destructive/50 bg-destructive/5 cursor-not-allowed"
+							: "border-border hover:border-primary/50 cursor-pointer"
+					}`}
+				>
+					<input
+						{...getInputProps()}
+						ref={fileInputRef}
+						className="hidden"
+						onClick={handleFileInputClick}
+					/>
+					{isFileCountLimitReached ? (
+						<div className="flex flex-col items-center gap-2 sm:gap-4 text-center px-4">
+							<Upload className="h-8 w-8 sm:h-12 sm:w-12 text-destructive/70" />
+							<div>
+								<p className="text-sm sm:text-lg font-medium text-destructive">
+									{t("file_limit_reached")}
+								</p>
+								<p className="text-xs sm:text-sm text-muted-foreground mt-1">
+									{t("file_limit_reached_desc", { max: MAX_FILES })}
+								</p>
 							</div>
-						) : isDragActive ? (
-							<div className="flex flex-col items-center gap-2 sm:gap-4">
-								<Upload className="h-8 w-8 sm:h-12 sm:w-12 text-primary" />
-								<p className="text-sm sm:text-lg font-medium text-primary">{t("drop_files")}</p>
+						</div>
+					) : isDragActive ? (
+						<div className="flex flex-col items-center gap-2 sm:gap-4">
+							<Upload className="h-8 w-8 sm:h-12 sm:w-12 text-primary" />
+							<p className="text-sm sm:text-lg font-medium text-primary">{t("drop_files")}</p>
+						</div>
+					) : (
+						<div className="flex flex-col items-center gap-2 sm:gap-4">
+							<Upload className="h-8 w-8 sm:h-12 sm:w-12 text-muted-foreground" />
+							<div className="text-center">
+								<p className="text-sm sm:text-lg font-medium">{t("drag_drop")}</p>
+								<p className="text-xs sm:text-sm text-muted-foreground mt-1">{t("or_browse")}</p>
 							</div>
-						) : (
-							<div className="flex flex-col items-center gap-2 sm:gap-4">
-								<Upload className="h-8 w-8 sm:h-12 sm:w-12 text-muted-foreground" />
-								<div className="text-center">
-									<p className="text-sm sm:text-lg font-medium">{t("drag_drop")}</p>
-									<p className="text-xs sm:text-sm text-muted-foreground mt-1">{t("or_browse")}</p>
-								</div>
-								{files.length > 0 && (
-									<p className="text-xs text-muted-foreground">
-										{t("remaining_capacity", { files: remainingFiles, sizeMB: remainingSizeMB })}
-									</p>
-								)}
-							</div>
-						)}
-						{!isFileCountLimitReached && (
-							<div className="mt-2 sm:mt-4">
+							{files.length > 0 && (
+								<p className="text-xs text-muted-foreground">
+									{t("remaining_capacity", { files: remainingFiles, sizeMB: remainingSizeMB })}
+								</p>
+							)}
+						</div>
+					)}
+					{!isFileCountLimitReached && (
+						<div className="mt-2 sm:mt-4">
+							{isElectron ? (
+								<Button
+									variant="secondary"
+									size="sm"
+									className="text-xs sm:text-sm"
+									onClick={handleBrowse}
+								>
+									{t("browse_files")}
+								</Button>
+							) : (
 								<Button
 									variant="secondary"
 									size="sm"
@@ -326,11 +433,76 @@ export function DocumentUploadTab({
 								>
 									{t("browse_files")}
 								</Button>
+							)}
+						</div>
+					)}
+				</div>
+			</CardContent>
+		</Card>
+
+		{selectedFolder && (
+			<Card className={cardClass}>
+				<CardHeader className="p-4 sm:p-6">
+					<div className="flex items-center justify-between gap-2">
+						<div className="flex items-center gap-3 min-w-0 flex-1">
+							<FolderOpen className="h-5 w-5 text-primary flex-shrink-0" />
+							<div className="min-w-0 flex-1">
+								<CardTitle className="text-base sm:text-lg truncate">
+									{selectedFolder.name}
+								</CardTitle>
+								<CardDescription className="text-xs sm:text-sm truncate">
+									{selectedFolder.path}
+								</CardDescription>
 							</div>
-						)}
+						</div>
+						<Button
+							variant="ghost"
+							size="icon"
+							className="h-8 w-8 shrink-0"
+							onClick={() => setSelectedFolder(null)}
+							disabled={folderSubmitting}
+						>
+							<X className="h-4 w-4" />
+						</Button>
 					</div>
+				</CardHeader>
+				<CardContent className="p-4 sm:p-6 pt-0 space-y-4">
+					<div className="flex items-center justify-between rounded-lg border border-border p-3">
+						<Label htmlFor="watch-folder-toggle" className="flex flex-col gap-1 cursor-pointer">
+							<span className="text-sm font-medium">Watch folder</span>
+							<span className="text-xs text-muted-foreground font-normal">
+								Automatically sync changes when files are added, edited, or removed
+							</span>
+						</Label>
+						<Switch
+							id="watch-folder-toggle"
+							checked={watchFolder}
+							onCheckedChange={setWatchFolder}
+						/>
+					</div>
+
+					<SummaryConfig enabled={shouldSummarize} onEnabledChange={setShouldSummarize} />
+
+					<Button
+						className="w-full py-3 sm:py-6 text-xs sm:text-base font-medium"
+						onClick={handleFolderSubmit}
+						disabled={folderSubmitting}
+					>
+						{folderSubmitting ? (
+							<span className="flex items-center gap-2">
+								<Spinner size="sm" />
+								Processing...
+							</span>
+						) : (
+							<span className="flex items-center gap-2">
+								<CheckCircle2 className="h-4 w-4 sm:h-5 sm:w-5" />
+								{watchFolder ? "Watch & Index Folder" : "Index Folder"}
+							</span>
+						)}
+					</Button>
 				</CardContent>
 			</Card>
+		)}
 
 			{files.length > 0 && (
 				<Card className={cardClass}>
diff --git a/surfsense_web/types/window.d.ts b/surfsense_web/types/window.d.ts
index b399664d6..826a575c7 100644
--- a/surfsense_web/types/window.d.ts
+++ b/surfsense_web/types/window.d.ts
@@ -26,6 +26,18 @@ interface FolderSyncWatcherReadyEvent {
 	folderPath: string;
 }
 
+interface BrowseResult {
+	type: "files" | "folder";
+	paths: string[];
+}
+
+interface LocalFileData {
+	name: string;
+	data: ArrayBuffer;
+	mimeType: string;
+	size: number;
+}
+
 interface ElectronAPI {
 	versions: {
 		electron: string;
@@ -51,6 +63,9 @@ interface ElectronAPI {
 	pauseWatcher: () => Promise<void>;
 	resumeWatcher: () => Promise<void>;
 	signalRendererReady: () => Promise<void>;
+	// Unified browse
+	browseFileOrFolder: () => Promise<BrowseResult | null>;
+	readLocalFiles: (paths: string[]) => Promise<LocalFileData[]>;
 }
 
 declare global {

From e0b35cfbabe43add555771e19166558376b30ff7 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 00:40:49 +0530
Subject: [PATCH 34/70] feat: implement pending file event handling using
 durable queue with acknowledgment support in folder synchronization

---
 surfsense_desktop/src/ipc/channels.ts         |   2 +
 surfsense_desktop/src/ipc/handlers.ts         |  10 ++
 .../src/modules/folder-watcher.ts             | 111 +++++++++++++++---
 surfsense_desktop/src/preload.ts              |   2 +
 surfsense_web/hooks/use-folder-sync.ts        |  82 +++++++++----
 surfsense_web/types/window.d.ts               |   3 +
 6 files changed, 175 insertions(+), 35 deletions(-)

diff --git a/surfsense_desktop/src/ipc/channels.ts b/surfsense_desktop/src/ipc/channels.ts
index 19c26607d..2761960f7 100644
--- a/surfsense_desktop/src/ipc/channels.ts
+++ b/surfsense_desktop/src/ipc/channels.ts
@@ -17,6 +17,8 @@ export const IPC_CHANNELS = {
   FOLDER_SYNC_PAUSE: 'folder-sync:pause',
   FOLDER_SYNC_RESUME: 'folder-sync:resume',
   FOLDER_SYNC_RENDERER_READY: 'folder-sync:renderer-ready',
+  FOLDER_SYNC_GET_PENDING_EVENTS: 'folder-sync:get-pending-events',
+  FOLDER_SYNC_ACK_EVENTS: 'folder-sync:ack-events',
   BROWSE_FILE_OR_FOLDER: 'browse:file-or-folder',
   READ_LOCAL_FILES: 'browse:read-local-files',
 } as const;
diff --git a/surfsense_desktop/src/ipc/handlers.ts b/surfsense_desktop/src/ipc/handlers.ts
index 246f0f6ac..7194aaaff 100644
--- a/surfsense_desktop/src/ipc/handlers.ts
+++ b/surfsense_desktop/src/ipc/handlers.ts
@@ -6,6 +6,8 @@ import {
   removeWatchedFolder,
   getWatchedFolders,
   getWatcherStatus,
+  getPendingFileEvents,
+  acknowledgeFileEvents,
   pauseWatcher,
   resumeWatcher,
   markRendererReady,
@@ -52,6 +54,14 @@ export function registerIpcHandlers(): void {
     markRendererReady();
   });
 
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_GET_PENDING_EVENTS, () =>
+    getPendingFileEvents()
+  );
+
+  ipcMain.handle(IPC_CHANNELS.FOLDER_SYNC_ACK_EVENTS, (_event, eventIds: string[]) =>
+    acknowledgeFileEvents(eventIds)
+  );
+
   ipcMain.handle(IPC_CHANNELS.BROWSE_FILE_OR_FOLDER, () => browseFileOrFolder());
 
   ipcMain.handle(IPC_CHANNELS.READ_LOCAL_FILES, (_event, paths: string[]) =>
diff --git a/surfsense_desktop/src/modules/folder-watcher.ts b/surfsense_desktop/src/modules/folder-watcher.ts
index 1324858a0..9cbdd9775 100644
--- a/surfsense_desktop/src/modules/folder-watcher.ts
+++ b/surfsense_desktop/src/modules/folder-watcher.ts
@@ -1,5 +1,6 @@
 import { BrowserWindow, dialog } from 'electron';
 import chokidar, { type FSWatcher } from 'chokidar';
+import { randomUUID } from 'crypto';
 import * as path from 'path';
 import * as fs from 'fs';
 import { IPC_CHANNELS } from '../ipc/channels';
@@ -20,12 +21,27 @@ interface WatcherEntry {
 }
 
 type MtimeMap = Record<string, number>;
+type FolderSyncAction = 'add' | 'change' | 'unlink';
+
+export interface FolderSyncFileChangedEvent {
+  id: string;
+  rootFolderId: number | null;
+  searchSpaceId: number;
+  folderPath: string;
+  folderName: string;
+  relativePath: string;
+  fullPath: string;
+  action: FolderSyncAction;
+  timestamp: number;
+}
 
 const STORE_KEY = 'watchedFolders';
+const OUTBOX_STORE_KEY = 'events';
 const MTIME_TOLERANCE_S = 1.0;
 
 let store: any = null;
 let mtimeStore: any = null;
+let outboxStore: any = null;
 let watchers: Map<string, WatcherEntry> = new Map();
 
 /**
@@ -35,22 +51,11 @@ let watchers: Map<string, WatcherEntry> = new Map();
 const mtimeMaps: Map<string, MtimeMap> = new Map();
 
 let rendererReady = false;
-const pendingEvents: any[] = [];
+const outboxEvents: Map<string, FolderSyncFileChangedEvent> = new Map();
+let outboxLoaded = false;
 
 export function markRendererReady() {
   rendererReady = true;
-  for (const event of pendingEvents) {
-    sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, event);
-  }
-  pendingEvents.length = 0;
-}
-
-function sendFileChangedEvent(data: any) {
-  if (rendererReady) {
-    sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, data);
-  } else {
-    pendingEvents.push(data);
-  }
 }
 
 async function getStore() {
@@ -77,6 +82,57 @@ async function getMtimeStore() {
   return mtimeStore;
 }
 
+async function getOutboxStore() {
+  if (!outboxStore) {
+    const { default: Store } = await import('electron-store');
+    outboxStore = new Store({
+      name: 'folder-sync-outbox',
+      defaults: {
+        [OUTBOX_STORE_KEY]: [] as FolderSyncFileChangedEvent[],
+      },
+    });
+  }
+  return outboxStore;
+}
+
+function makeEventKey(event: Pick<FolderSyncFileChangedEvent, 'folderPath' | 'relativePath'>): string {
+  return `${event.folderPath}:${event.relativePath}`;
+}
+
+function persistOutbox() {
+  getOutboxStore().then((s) => {
+    s.set(OUTBOX_STORE_KEY, Array.from(outboxEvents.values()));
+  });
+}
+
+async function loadOutbox() {
+  if (outboxLoaded) return;
+  const s = await getOutboxStore();
+  const stored: FolderSyncFileChangedEvent[] = s.get(OUTBOX_STORE_KEY, []);
+  outboxEvents.clear();
+  for (const event of stored) {
+    if (!event?.id || !event.folderPath || !event.relativePath) continue;
+    outboxEvents.set(makeEventKey(event), event);
+  }
+  outboxLoaded = true;
+}
+
+function sendFileChangedEvent(
+  data: Omit<FolderSyncFileChangedEvent, 'id'>
+) {
+  const event: FolderSyncFileChangedEvent = {
+    id: randomUUID(),
+    ...data,
+  };
+
+  outboxEvents.set(makeEventKey(event), event);
+  persistOutbox();
+
+  if (rendererReady) {
+    sendToRenderer(IPC_CHANNELS.FOLDER_SYNC_FILE_CHANGED, event);
+  }
+}
+
 function loadMtimeMap(folderPath: string): MtimeMap {
   return mtimeMaps.get(folderPath) ?? {};
 }
@@ -235,7 +291,7 @@ async function startWatcher(config: WatchedFolderConfig) {
     });
   });
 
-  const handleFileEvent = (filePath: string, action: string) => {
+  const handleFileEvent = (filePath: string, action: FolderSyncAction) => {
     if (!ready) return;
 
     const relativePath = path.relative(config.path, filePath);
@@ -357,6 +413,32 @@ export async function getWatcherStatus(): Promise<
   }));
 }
 
+export async function getPendingFileEvents(): Promise<FolderSyncFileChangedEvent[]> {
+  await loadOutbox();
+  return Array.from(outboxEvents.values()).sort((a, b) => a.timestamp - b.timestamp);
+}
+
+export async function acknowledgeFileEvents(eventIds: string[]): Promise<{ acknowledged: number }> {
+  if (!eventIds || eventIds.length === 0) return { acknowledged: 0 };
+  await loadOutbox();
+
+  const ackSet = new Set(eventIds);
+  let acknowledged = 0;
+
+  for (const [key, event] of outboxEvents.entries()) {
+    if (ackSet.has(event.id)) {
+      outboxEvents.delete(key);
+      acknowledged += 1;
+    }
+  }
+
+  if (acknowledged > 0) {
+    persistOutbox();
+  }
+
+  return { acknowledged };
+}
+
 export async function pauseWatcher(): Promise<void> {
   for (const [, entry] of watchers) {
     if (entry.watcher) {
@@ -375,6 +457,7 @@ export async function resumeWatcher(): Promise<void> {
 }
 
 export async function registerFolderWatcher(): Promise<void> {
+  await loadOutbox();
   const s = await getStore();
   const folders: WatchedFolderConfig[] = s.get(STORE_KEY, []);
 
diff --git a/surfsense_desktop/src/preload.ts b/surfsense_desktop/src/preload.ts
index 08ca87f8f..6a2610dc8 100644
--- a/surfsense_desktop/src/preload.ts
+++ b/surfsense_desktop/src/preload.ts
@@ -45,6 +45,8 @@ contextBridge.exposeInMainWorld('electronAPI', {
   pauseWatcher: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_PAUSE),
   resumeWatcher: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_RESUME),
   signalRendererReady: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_RENDERER_READY),
+  getPendingFileEvents: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_GET_PENDING_EVENTS),
+  acknowledgeFileEvents: (eventIds: string[]) => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_ACK_EVENTS, eventIds),
 
   // Unified browse (files + folders)
   browseFileOrFolder: () => ipcRenderer.invoke(IPC_CHANNELS.BROWSE_FILE_OR_FOLDER),
diff --git a/surfsense_web/hooks/use-folder-sync.ts b/surfsense_web/hooks/use-folder-sync.ts
index f051b7df6..59c061afb 100644
--- a/surfsense_web/hooks/use-folder-sync.ts
+++ b/surfsense_web/hooks/use-folder-sync.ts
@@ -4,6 +4,7 @@ import { useEffect, useRef } from "react";
 import { documentsApiService } from "@/lib/apis/documents-api.service";
 
 interface FileChangedEvent {
+	id: string;
 	rootFolderId: number | null;
 	searchSpaceId: number;
 	folderPath: string;
@@ -15,25 +16,35 @@ interface FileChangedEvent {
 }
 
 const DEBOUNCE_MS = 2000;
+interface QueueItem {
+	event: FileChangedEvent;
+	ackIds: string[];
+}
 
 export function useFolderSync() {
-	const queueRef = useRef<FileChangedEvent[]>([]);
+	const queueRef = useRef<QueueItem[]>([]);
 	const processingRef = useRef(false);
 	const debounceTimers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
+	const pendingByKey = useRef<Map<string, QueueItem>>(new Map());
+	const isMountedRef = useRef(false);
 
 	async function processQueue() {
 		if (processingRef.current) return;
 		processingRef.current = true;
 		while (queueRef.current.length > 0) {
-			const event = queueRef.current.shift()!;
+			const item = queueRef.current.shift()!;
 			try {
-				await documentsApiService.folderIndexFile(event.searchSpaceId, {
-					folder_path: event.folderPath,
-					folder_name: event.folderName,
-					search_space_id: event.searchSpaceId,
-					target_file_path: event.fullPath,
-					root_folder_id: event.rootFolderId,
+				await documentsApiService.folderIndexFile(item.event.searchSpaceId, {
+					folder_path: item.event.folderPath,
+					folder_name: item.event.folderName,
+					search_space_id: item.event.searchSpaceId,
+					target_file_path: item.event.fullPath,
+					root_folder_id: item.event.rootFolderId,
 				});
+				const api = typeof window !== "undefined" ? window.electronAPI : null;
+				if (api?.acknowledgeFileEvents && item.ackIds.length > 0) {
+					await api.acknowledgeFileEvents(item.ackIds);
+				}
 			} catch (err) {
 				console.error("[FolderSync] Failed to trigger re-index:", err);
 			}
@@ -41,34 +52,63 @@ export function useFolderSync() {
 		processingRef.current = false;
 	}
 
+	function enqueueWithDebounce(event: FileChangedEvent) {
+		const key = `${event.folderPath}:${event.relativePath}`;
+		const existing = pendingByKey.current.get(key);
+		const ackSet = new Set(existing?.ackIds ?? []);
+		ackSet.add(event.id);
+		pendingByKey.current.set(key, {
+			event,
+			ackIds: Array.from(ackSet),
+		});
+
+		const existingTimeout = debounceTimers.current.get(key);
+		if (existingTimeout) clearTimeout(existingTimeout);
+
+		const timeout = setTimeout(() => {
+			debounceTimers.current.delete(key);
+			const pending = pendingByKey.current.get(key);
+			if (!pending) return;
+			pendingByKey.current.delete(key);
+			queueRef.current.push(pending);
+			processQueue();
+		}, DEBOUNCE_MS);
+
+		debounceTimers.current.set(key, timeout);
+	}
+
 	useEffect(() => {
+		isMountedRef.current = true;
 		const api = typeof window !== "undefined" ? window.electronAPI : null;
-		if (!api?.onFileChanged) return;
+		if (!api?.onFileChanged) {
+			return () => {
+				isMountedRef.current = false;
+			};
+		}
 
 		// Signal to main process that the renderer is ready to receive events
 		api.signalRendererReady?.();
 
+		// Drain durable outbox first so events survive renderer startup gaps and restarts
+		void api.getPendingFileEvents?.().then((pendingEvents) => {
+			if (!isMountedRef.current || !pendingEvents?.length) return;
+			for (const event of pendingEvents) {
+				enqueueWithDebounce(event);
+			}
+		});
+
 		const cleanup = api.onFileChanged((event: FileChangedEvent) => {
-			const key = `${event.folderPath}:${event.fullPath}`;
-
-			const existing = debounceTimers.current.get(key);
-			if (existing) clearTimeout(existing);
-
-			const timeout = setTimeout(() => {
-				debounceTimers.current.delete(key);
-				queueRef.current.push(event);
-				processQueue();
-			}, DEBOUNCE_MS);
-
-			debounceTimers.current.set(key, timeout);
+			enqueueWithDebounce(event);
 		});
 
 		return () => {
+			isMountedRef.current = false;
 			cleanup();
 			for (const timeout of debounceTimers.current.values()) {
 				clearTimeout(timeout);
 			}
 			debounceTimers.current.clear();
+			pendingByKey.current.clear();
 		};
 	}, []);
 }
diff --git a/surfsense_web/types/window.d.ts b/surfsense_web/types/window.d.ts
index 826a575c7..719373e02 100644
--- a/surfsense_web/types/window.d.ts
+++ b/surfsense_web/types/window.d.ts
@@ -11,6 +11,7 @@ interface WatchedFolderConfig {
 }
 
 interface FolderSyncFileChangedEvent {
+	id: string;
 	rootFolderId: number | null;
 	searchSpaceId: number;
 	folderPath: string;
@@ -63,6 +64,8 @@ interface ElectronAPI {
 	pauseWatcher: () => Promise<void>;
 	resumeWatcher: () => Promise<void>;
 	signalRendererReady: () => Promise<void>;
+	getPendingFileEvents: () => Promise<FolderSyncFileChangedEvent[]>;
+	acknowledgeFileEvents: (eventIds: string[]) => Promise<{ acknowledged: number }>;
 	// Unified browse
 	browseFileOrFolder: () => Promise<BrowseResult | null>;
 	readLocalFiles: (paths: string[]) => Promise<LocalFileData[]>;

From 530db1053939cd69a6ce41107a6169babab1f707 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 02:56:24 +0530
Subject: [PATCH 35/70] refactor: remove unused Electron API check and update
 search space ID handling in document upload

---
 surfsense_desktop/src/ipc/channels.ts         |   2 +-
 surfsense_desktop/src/ipc/handlers.ts         |   4 +-
 .../src/modules/folder-watcher.ts             |  18 +-
 surfsense_desktop/src/preload.ts              |   4 +-
 .../layout/ui/sidebar/DocumentsSidebar.tsx    |   2 -
 .../components/sources/DocumentUploadTab.tsx  | 162 ++++++++++--------
 surfsense_web/types/window.d.ts               |   9 +-
 7 files changed, 100 insertions(+), 101 deletions(-)

diff --git a/surfsense_desktop/src/ipc/channels.ts b/surfsense_desktop/src/ipc/channels.ts
index 2761960f7..2000964c7 100644
--- a/surfsense_desktop/src/ipc/channels.ts
+++ b/surfsense_desktop/src/ipc/channels.ts
@@ -19,6 +19,6 @@ export const IPC_CHANNELS = {
   FOLDER_SYNC_RENDERER_READY: 'folder-sync:renderer-ready',
   FOLDER_SYNC_GET_PENDING_EVENTS: 'folder-sync:get-pending-events',
   FOLDER_SYNC_ACK_EVENTS: 'folder-sync:ack-events',
-  BROWSE_FILE_OR_FOLDER: 'browse:file-or-folder',
+  BROWSE_FILES: 'browse:files',
   READ_LOCAL_FILES: 'browse:read-local-files',
 } as const;
diff --git a/surfsense_desktop/src/ipc/handlers.ts b/surfsense_desktop/src/ipc/handlers.ts
index 7194aaaff..c4251b30b 100644
--- a/surfsense_desktop/src/ipc/handlers.ts
+++ b/surfsense_desktop/src/ipc/handlers.ts
@@ -11,7 +11,7 @@ import {
   pauseWatcher,
   resumeWatcher,
   markRendererReady,
-  browseFileOrFolder,
+  browseFiles,
   readLocalFiles,
 } from '../modules/folder-watcher';
 
@@ -62,7 +62,7 @@ export function registerIpcHandlers(): void {
     acknowledgeFileEvents(eventIds)
   );
 
-  ipcMain.handle(IPC_CHANNELS.BROWSE_FILE_OR_FOLDER, () => browseFileOrFolder());
+  ipcMain.handle(IPC_CHANNELS.BROWSE_FILES, () => browseFiles());
 
   ipcMain.handle(IPC_CHANNELS.READ_LOCAL_FILES, (_event, paths: string[]) =>
     readLocalFiles(paths)
diff --git a/surfsense_desktop/src/modules/folder-watcher.ts b/surfsense_desktop/src/modules/folder-watcher.ts
index 9cbdd9775..969dabe97 100644
--- a/surfsense_desktop/src/modules/folder-watcher.ts
+++ b/surfsense_desktop/src/modules/folder-watcher.ts
@@ -475,23 +475,13 @@ export async function unregisterFolderWatcher(): Promise<void> {
   watchers.clear();
 }
 
-export interface BrowseResult {
-  type: 'files' | 'folder';
-  paths: string[];
-}
-
-export async function browseFileOrFolder(): Promise<BrowseResult | null> {
+export async function browseFiles(): Promise<string[] | null> {
   const result = await dialog.showOpenDialog({
-    properties: ['openFile', 'openDirectory', 'multiSelections'],
-    title: 'Select files or a folder',
+    properties: ['openFile', 'multiSelections'],
+    title: 'Select files',
   });
   if (result.canceled || result.filePaths.length === 0) return null;
-
-  const stat = fs.statSync(result.filePaths[0]);
-  if (stat.isDirectory()) {
-    return { type: 'folder', paths: [result.filePaths[0]] };
-  }
-  return { type: 'files', paths: result.filePaths };
+  return result.filePaths;
 }
 
 const MIME_MAP: Record<string, string> = {
diff --git a/surfsense_desktop/src/preload.ts b/surfsense_desktop/src/preload.ts
index 6a2610dc8..6fbfd354a 100644
--- a/surfsense_desktop/src/preload.ts
+++ b/surfsense_desktop/src/preload.ts
@@ -48,7 +48,7 @@ contextBridge.exposeInMainWorld('electronAPI', {
   getPendingFileEvents: () => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_GET_PENDING_EVENTS),
   acknowledgeFileEvents: (eventIds: string[]) => ipcRenderer.invoke(IPC_CHANNELS.FOLDER_SYNC_ACK_EVENTS, eventIds),
 
-  // Unified browse (files + folders)
-  browseFileOrFolder: () => ipcRenderer.invoke(IPC_CHANNELS.BROWSE_FILE_OR_FOLDER),
+  // Browse files via native dialog
+  browseFiles: () => ipcRenderer.invoke(IPC_CHANNELS.BROWSE_FILES),
   readLocalFiles: (paths: string[]) => ipcRenderer.invoke(IPC_CHANNELS.READ_LOCAL_FILES, paths),
 });
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index ed3a78786..f8b774d26 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -277,8 +277,6 @@ export function DocumentsSidebar({
 		[createFolderParentId, searchSpaceId, setExpandedFolderMap]
 	);
 
-	const isElectron = typeof window !== "undefined" && !!window.electronAPI;
-
 	const handleRescanFolder = useCallback(
 		async (folder: FolderDisplay) => {
 			const api = window.electronAPI;
diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index 3fdf576b5..d5ac2770a 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAtom } from "jotai";
-import { CheckCircle2, FileType, FolderOpen, Info, Upload, X } from "lucide-react";
+import { CheckCircle2, ChevronDown, File as FileIcon, FileType, FolderOpen, Info, Upload, X } from "lucide-react";
 
 import { useTranslations } from "next-intl";
 import { useCallback, useMemo, useRef, useState } from "react";
@@ -19,6 +19,12 @@ import { Alert, AlertDescription } from "@/components/ui/alert";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import {
+	DropdownMenu,
+	DropdownMenuContent,
+	DropdownMenuItem,
+	DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
 import { Label } from "@/components/ui/label";
 import { Progress } from "@/components/ui/progress";
 import { Separator } from "@/components/ui/separator";
@@ -146,7 +152,7 @@ export function DocumentUploadTab({
 	const [selectedFolder, setSelectedFolder] = useState<SelectedFolder | null>(null);
 	const [watchFolder, setWatchFolder] = useState(true);
 	const [folderSubmitting, setFolderSubmitting] = useState(false);
-	const isElectron = typeof window !== "undefined" && !!window.electronAPI?.browseFileOrFolder;
+	const isElectron = typeof window !== "undefined" && !!window.electronAPI?.browseFiles;
 
 	const acceptedFileTypes = useMemo(() => {
 		const etlService = process.env.NEXT_PUBLIC_ETL_SERVICE;
@@ -193,7 +199,7 @@ export function DocumentUploadTab({
 		onDrop,
 		accept: acceptedFileTypes,
 		maxSize: 50 * 1024 * 1024, // 50MB per file
-		noClick: !isElectron,
+		noClick: isElectron,
 		disabled: files.length >= MAX_FILES,
 	});
 
@@ -201,52 +207,51 @@ export function DocumentUploadTab({
 		e.stopPropagation();
 	}, []);
 
-	const handleBrowse = useCallback(async (e: React.MouseEvent) => {
-		e.stopPropagation();
-		e.preventDefault();
-
+	const handleBrowseFiles = useCallback(async () => {
 		const api = window.electronAPI;
-		if (!api?.browseFileOrFolder) {
-			fileInputRef.current?.click();
-			return;
-		}
+		if (!api?.browseFiles) return;
 
-		const result = await api.browseFileOrFolder();
-		if (!result) return;
+		const paths = await api.browseFiles();
+		if (!paths || paths.length === 0) return;
 
-		if (result.type === "folder") {
-			const folderPath = result.paths[0];
-			const folderName = folderPath.split("/").pop() || folderPath.split("\\").pop() || folderPath;
-			setFiles([]);
-			setSelectedFolder({ path: folderPath, name: folderName });
-			setWatchFolder(true);
-		} else {
-			setSelectedFolder(null);
-			const fileDataList = await api.readLocalFiles(result.paths);
-			const newFiles: FileWithId[] = fileDataList.map((fd) => ({
-				id: crypto.randomUUID?.() ?? `file-${Date.now()}-${Math.random().toString(36)}`,
-				file: new File([fd.data], fd.name, { type: fd.mimeType }),
-			}));
-			setFiles((prev) => {
-				const merged = [...prev, ...newFiles];
-				if (merged.length > MAX_FILES) {
-					toast.error(t("max_files_exceeded"), {
-						description: t("max_files_exceeded_desc", { max: MAX_FILES }),
-					});
-					return prev;
-				}
-				const totalSize = merged.reduce((sum, e) => sum + e.file.size, 0);
-				if (totalSize > MAX_TOTAL_SIZE_BYTES) {
-					toast.error(t("max_size_exceeded"), {
-						description: t("max_size_exceeded_desc", { max: MAX_TOTAL_SIZE_MB }),
-					});
-					return prev;
-				}
-				return merged;
-			});
-		}
+		setSelectedFolder(null);
+		const fileDataList = await api.readLocalFiles(paths);
+		const newFiles: FileWithId[] = fileDataList.map((fd) => ({
+			id: crypto.randomUUID?.() ?? `file-${Date.now()}-${Math.random().toString(36)}`,
+			file: new File([fd.data], fd.name, { type: fd.mimeType }),
+		}));
+		setFiles((prev) => {
+			const merged = [...prev, ...newFiles];
+			if (merged.length > MAX_FILES) {
+				toast.error(t("max_files_exceeded"), {
+					description: t("max_files_exceeded_desc", { max: MAX_FILES }),
+				});
+				return prev;
+			}
+			const totalSize = merged.reduce((sum, e) => sum + e.file.size, 0);
+			if (totalSize > MAX_TOTAL_SIZE_BYTES) {
+				toast.error(t("max_size_exceeded"), {
+					description: t("max_size_exceeded_desc", { max: MAX_TOTAL_SIZE_MB }),
+				});
+				return prev;
+			}
+			return merged;
+		});
 	}, [t]);
 
+	const handleBrowseFolder = useCallback(async () => {
+		const api = window.electronAPI;
+		if (!api?.selectFolder) return;
+
+		const folderPath = await api.selectFolder();
+		if (!folderPath) return;
+
+		const folderName = folderPath.split("/").pop() || folderPath.split("\\").pop() || folderPath;
+		setFiles([]);
+		setSelectedFolder({ path: folderPath, name: folderName });
+		setWatchFolder(true);
+	}, []);
+
 	const formatFileSize = (bytes: number) => {
 		if (bytes === 0) return "0 Bytes";
 		const k = 1024;
@@ -280,10 +285,11 @@ export function DocumentUploadTab({
 
 		setFolderSubmitting(true);
 		try {
-			const result = await documentsApiService.folderIndex(Number(searchSpaceId), {
+			const numericSpaceId = Number(searchSpaceId);
+			const result = await documentsApiService.folderIndex(numericSpaceId, {
 				folder_path: selectedFolder.path,
 				folder_name: selectedFolder.name,
-				search_space_id: searchSpaceId,
+				search_space_id: numericSpaceId,
 				enable_summary: shouldSummarize,
 			});
 
@@ -409,33 +415,43 @@ export function DocumentUploadTab({
 							)}
 						</div>
 					)}
-					{!isFileCountLimitReached && (
-						<div className="mt-2 sm:mt-4">
-							{isElectron ? (
-								<Button
-									variant="secondary"
-									size="sm"
-									className="text-xs sm:text-sm"
-									onClick={handleBrowse}
-								>
-									{t("browse_files")}
-								</Button>
-							) : (
-								<Button
-									variant="secondary"
-									size="sm"
-									className="text-xs sm:text-sm"
-									onClick={(e) => {
-										e.stopPropagation();
-										e.preventDefault();
-										fileInputRef.current?.click();
-									}}
-								>
-									{t("browse_files")}
-								</Button>
-							)}
-						</div>
-					)}
+				{!isFileCountLimitReached && (
+					<div className="mt-2 sm:mt-4">
+						{isElectron ? (
+							<DropdownMenu>
+								<DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
+									<Button variant="secondary" size="sm" className="text-xs sm:text-sm gap-1">
+										{t("browse_files")}
+										<ChevronDown className="h-3 w-3 opacity-60" />
+									</Button>
+								</DropdownMenuTrigger>
+								<DropdownMenuContent align="center" onClick={(e) => e.stopPropagation()}>
+									<DropdownMenuItem onClick={handleBrowseFiles}>
+										<FileIcon className="h-4 w-4 mr-2" />
+										Files
+									</DropdownMenuItem>
+									<DropdownMenuItem onClick={handleBrowseFolder}>
+										<FolderOpen className="h-4 w-4 mr-2" />
+										Folder
+									</DropdownMenuItem>
+								</DropdownMenuContent>
+							</DropdownMenu>
+						) : (
+							<Button
+								variant="secondary"
+								size="sm"
+								className="text-xs sm:text-sm"
+								onClick={(e) => {
+									e.stopPropagation();
+									e.preventDefault();
+									fileInputRef.current?.click();
+								}}
+							>
+								{t("browse_files")}
+							</Button>
+						)}
+					</div>
+				)}
 				</div>
 			</CardContent>
 		</Card>
diff --git a/surfsense_web/types/window.d.ts b/surfsense_web/types/window.d.ts
index 719373e02..0842ed655 100644
--- a/surfsense_web/types/window.d.ts
+++ b/surfsense_web/types/window.d.ts
@@ -27,11 +27,6 @@ interface FolderSyncWatcherReadyEvent {
 	folderPath: string;
 }
 
-interface BrowseResult {
-	type: "files" | "folder";
-	paths: string[];
-}
-
 interface LocalFileData {
 	name: string;
 	data: ArrayBuffer;
@@ -66,8 +61,8 @@ interface ElectronAPI {
 	signalRendererReady: () => Promise<void>;
 	getPendingFileEvents: () => Promise<FolderSyncFileChangedEvent[]>;
 	acknowledgeFileEvents: (eventIds: string[]) => Promise<{ acknowledged: number }>;
-	// Unified browse
-	browseFileOrFolder: () => Promise<BrowseResult | null>;
+	// Browse files/folders via native dialogs
+	browseFiles: () => Promise<string[] | null>;
 	readLocalFiles: (paths: string[]) => Promise<LocalFileData[]>;
 }
 

From bd21c2842dec8dfeae80a00a040c4b1513c1cf3d Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 04:14:09 +0530
Subject: [PATCH 36/70] feat: enhance document upload and folder
 synchronization UI with improved processing state indicators and responsive
 design adjustments

---
 .../app/routes/documents_routes.py            |   5 +-
 .../assistant-ui/document-upload-popup.tsx    |  29 +-
 .../components/documents/DocumentNode.tsx     |  14 +-
 .../components/documents/FolderNode.tsx       |  48 +-
 .../components/documents/FolderTreeView.tsx   |  30 +
 .../components/sources/DocumentUploadTab.tsx  | 514 +++++++++---------
 .../contracts/enums/connectorIcons.tsx        |   2 +
 7 files changed, 359 insertions(+), 283 deletions(-)

diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index 0acc1d30b..edb01d4cc 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -29,6 +29,7 @@ from app.schemas import (
     DocumentTitleSearchResponse,
     DocumentUpdate,
     DocumentWithChunksRead,
+    FolderRead,
     PaginatedResponse,
 )
 from app.services.task_dispatcher import TaskDispatcher, get_task_dispatcher
@@ -953,15 +954,13 @@ async def get_document_by_chunk_id(
         ) from e
 
 
-@router.get("/documents/watched-folders", response_model=list["FolderRead"])
+@router.get("/documents/watched-folders", response_model=list[FolderRead])
 async def get_watched_folders(
     search_space_id: int,
     session: AsyncSession = Depends(get_async_session),
     user: User = Depends(current_active_user),
 ):
     """Return root folders that are marked as watched (metadata->>'watched' = 'true')."""
-    from app.schemas import FolderRead  # noqa: F811
-
     await check_permission(
         session,
         user,
diff --git a/surfsense_web/components/assistant-ui/document-upload-popup.tsx b/surfsense_web/components/assistant-ui/document-upload-popup.tsx
index 06b0d38e7..78600be47 100644
--- a/surfsense_web/components/assistant-ui/document-upload-popup.tsx
+++ b/surfsense_web/components/assistant-ui/document-upload-popup.tsx
@@ -125,29 +125,23 @@ const DocumentUploadPopupContent: FC<{
 				onPointerDownOutside={(e) => e.preventDefault()}
 				onInteractOutside={(e) => e.preventDefault()}
 				onEscapeKeyDown={(e) => e.preventDefault()}
-				className="select-none max-w-4xl w-[95vw] sm:w-full h-[calc(100dvh-2rem)] sm:h-[85vh] flex flex-col p-0 gap-0 overflow-hidden border border-border ring-0 bg-muted dark:bg-muted text-foreground [&>button]:right-3 sm:[&>button]:right-12 [&>button]:top-3 sm:[&>button]:top-10 [&>button]:opacity-80 hover:[&>button]:opacity-100 [&>button]:z-[100] [&>button_svg]:size-4 sm:[&>button_svg]:size-5"
+				className="select-none max-w-2xl w-[95vw] sm:w-[640px] h-[min(460px,75dvh)] sm:h-[min(520px,80vh)] flex flex-col p-0 gap-0 overflow-hidden border border-border ring-0 bg-muted dark:bg-muted text-foreground [&>button]:right-3 sm:[&>button]:right-6 [&>button]:top-3 sm:[&>button]:top-5 [&>button]:opacity-80 hover:[&>button]:opacity-100 [&>button]:z-[100] [&>button_svg]:size-4 sm:[&>button_svg]:size-5"
 			>
 				<DialogTitle className="sr-only">Upload Document</DialogTitle>
 
-				{/* Scrollable container for mobile */}
 				<div className="flex-1 min-h-0 overflow-y-auto overscroll-contain">
-					{/* Header - scrolls with content on mobile */}
-					<div className="sticky top-0 z-20 bg-muted px-4 sm:px-12 pt-4 sm:pt-10 pb-2 sm:pb-0">
-						{/* Upload header */}
-						<div className="flex items-center gap-2 sm:gap-4 mb-2 sm:mb-6">
-							<div className="flex-1 min-w-0 pr-8 sm:pr-0">
-								<h2 className="text-base sm:text-2xl font-semibold tracking-tight">
-									Upload Documents
-								</h2>
-								<p className="text-xs sm:text-base text-muted-foreground mt-0.5 sm:mt-1 line-clamp-1 sm:line-clamp-none">
-									Upload and sync your documents to your search space
-								</p>
-							</div>
+					<div className="sticky top-0 z-20 bg-muted px-4 sm:px-6 pt-4 sm:pt-5 pb-10">
+						<div className="flex items-center gap-2 mb-1 pr-8 sm:pr-0">
+							<h2 className="text-base sm:text-lg font-semibold tracking-tight">
+								Upload Documents
+							</h2>
 						</div>
+						<p className="text-xs sm:text-sm text-muted-foreground line-clamp-1">
+							Upload and sync your documents to your search space
+						</p>
 					</div>
 
-					{/* Content */}
-					<div className="px-4 sm:px-12 pb-4 sm:pb-16">
+					<div className="px-4 sm:px-6 pb-4 sm:pb-6">
 						{!isLoading && !hasDocumentSummaryLLM ? (
 							<Alert variant="destructive" className="mb-4 bg-muted/50 rounded-xl border-destructive/30">
 								<AlertTriangle className="h-4 w-4" />
@@ -179,9 +173,6 @@ const DocumentUploadPopupContent: FC<{
 						)}
 					</div>
 				</div>
-
-				{/* Bottom fade shadow - hidden on very small screens */}
-				<div className="hidden sm:block absolute bottom-0 left-0 right-0 h-7 bg-gradient-to-t from-muted via-muted/80 to-transparent pointer-events-none z-10" />
 			</DialogContent>
 		</Dialog>
 	);
diff --git a/surfsense_web/components/documents/DocumentNode.tsx b/surfsense_web/components/documents/DocumentNode.tsx
index 691a6eb0d..7a3b3e0ca 100644
--- a/surfsense_web/components/documents/DocumentNode.tsx
+++ b/surfsense_web/components/documents/DocumentNode.tsx
@@ -195,12 +195,14 @@ export const DocumentNode = React.memo(function DocumentNode({
 
 					<span className="flex-1 min-w-0 truncate">{doc.title}</span>
 
-					<span className="shrink-0">
-						{getDocumentTypeIcon(
-							doc.document_type as DocumentTypeEnum,
-							"h-3.5 w-3.5 text-muted-foreground"
-						)}
-					</span>
+					{getDocumentTypeIcon(doc.document_type as DocumentTypeEnum, "h-3.5 w-3.5 text-muted-foreground") && (
+						<span className="shrink-0">
+							{getDocumentTypeIcon(
+								doc.document_type as DocumentTypeEnum,
+								"h-3.5 w-3.5 text-muted-foreground"
+							)}
+						</span>
+					)}
 
 					<DropdownMenu open={dropdownOpen} onOpenChange={setDropdownOpen}>
 						<DropdownMenuTrigger asChild>
diff --git a/surfsense_web/components/documents/FolderNode.tsx b/surfsense_web/components/documents/FolderNode.tsx
index 6780bd1e5..41c1d8f73 100644
--- a/surfsense_web/components/documents/FolderNode.tsx
+++ b/surfsense_web/components/documents/FolderNode.tsx
@@ -1,6 +1,7 @@
 "use client";
 
 import {
+	AlertCircle,
 	ChevronDown,
 	ChevronRight,
 	Eye,
@@ -30,6 +31,8 @@ import {
 	DropdownMenuItem,
 	DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
+import { Spinner } from "@/components/ui/spinner";
+import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import { cn } from "@/lib/utils";
 import type { FolderSelectionState } from "./FolderTreeView";
 
@@ -55,6 +58,7 @@ interface FolderNodeProps {
 	isRenaming: boolean;
 	childCount: number;
 	selectionState: FolderSelectionState;
+	processingState: "idle" | "processing" | "failed";
 	onToggleSelect: (folderId: number, selectAll: boolean) => void;
 	onToggleExpand: (folderId: number) => void;
 	onRename: (folder: FolderDisplay, newName: string) => void;
@@ -100,6 +104,7 @@ export const FolderNode = React.memo(function FolderNode({
 	isRenaming,
 	childCount,
 	selectionState,
+	processingState,
 	onToggleSelect,
 	onToggleExpand,
 	onRename,
@@ -281,14 +286,41 @@ export const FolderNode = React.memo(function FolderNode({
 						)}
 					</span>
 
-					<Checkbox
-						checked={
-							selectionState === "all" ? true : selectionState === "some" ? "indeterminate" : false
-						}
-						onCheckedChange={handleCheckChange}
-						onClick={(e) => e.stopPropagation()}
-						className="h-3.5 w-3.5 shrink-0"
-					/>
+					{processingState !== "idle" && selectionState === "none" ? (
+						<>
+							<Tooltip>
+								<TooltipTrigger asChild>
+									<span className="flex h-3.5 w-3.5 shrink-0 items-center justify-center group-hover:hidden">
+										{processingState === "processing" ? (
+											<Spinner size="xs" className="text-primary" />
+										) : (
+											<AlertCircle className="h-3.5 w-3.5 text-destructive" />
+										)}
+									</span>
+								</TooltipTrigger>
+								<TooltipContent side="top">
+									{processingState === "processing"
+										? "Syncing folder contents"
+										: "Some files failed to process"}
+								</TooltipContent>
+							</Tooltip>
+							<Checkbox
+								checked={false}
+								onCheckedChange={handleCheckChange}
+								onClick={(e) => e.stopPropagation()}
+								className="h-3.5 w-3.5 shrink-0 hidden group-hover:flex"
+							/>
+						</>
+					) : (
+						<Checkbox
+							checked={
+								selectionState === "all" ? true : selectionState === "some" ? "indeterminate" : false
+							}
+							onCheckedChange={handleCheckChange}
+							onClick={(e) => e.stopPropagation()}
+							className="h-3.5 w-3.5 shrink-0"
+						/>
+					)}
 
 					<FolderIcon className="h-4 w-4 shrink-0 text-muted-foreground" />
 
diff --git a/surfsense_web/components/documents/FolderTreeView.tsx b/surfsense_web/components/documents/FolderTreeView.tsx
index f34b9a0c2..01af73edc 100644
--- a/surfsense_web/components/documents/FolderTreeView.tsx
+++ b/surfsense_web/components/documents/FolderTreeView.tsx
@@ -166,6 +166,35 @@ export function FolderTreeView({
 		return states;
 	}, [folders, docsByFolder, foldersByParent, mentionedDocIds]);
 
+	const folderProcessingStates = useMemo(() => {
+		const states: Record<number, "idle" | "processing" | "failed"> = {};
+
+		function compute(folderId: number): { hasProcessing: boolean; hasFailed: boolean } {
+			const directDocs = docsByFolder[folderId] ?? [];
+			let hasProcessing = directDocs.some(
+				(d) => d.status?.state === "pending" || d.status?.state === "processing"
+			);
+			let hasFailed = directDocs.some((d) => d.status?.state === "failed");
+
+			for (const child of foldersByParent[folderId] ?? []) {
+				const sub = compute(child.id);
+				hasProcessing = hasProcessing || sub.hasProcessing;
+				hasFailed = hasFailed || sub.hasFailed;
+			}
+
+			if (hasProcessing) states[folderId] = "processing";
+			else if (hasFailed) states[folderId] = "failed";
+			else states[folderId] = "idle";
+
+			return { hasProcessing, hasFailed };
+		}
+
+		for (const f of folders) {
+			if (states[f.id] === undefined) compute(f.id);
+		}
+		return states;
+	}, [folders, docsByFolder, foldersByParent]);
+
 	function renderLevel(parentId: number | null, depth: number): React.ReactNode[] {
 		const key = parentId ?? "root";
 		const childFolders = (foldersByParent[key] ?? [])
@@ -199,6 +228,7 @@ export function FolderTreeView({
 					isRenaming={renamingFolderId === f.id}
 					childCount={folderChildCounts[f.id] ?? 0}
 					selectionState={folderSelectionStates[f.id] ?? "none"}
+					processingState={folderProcessingStates[f.id] ?? "idle"}
 					onToggleSelect={onToggleFolderSelect}
 					onToggleExpand={onToggleExpand}
 					onRename={onRenameFolder}
diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index d5ac2770a..7176afae5 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -1,24 +1,21 @@
 "use client";
 
 import { useAtom } from "jotai";
-import { CheckCircle2, ChevronDown, File as FileIcon, FileType, FolderOpen, Info, Upload, X } from "lucide-react";
+import { CheckCircle2, ChevronDown, File as FileIcon, FileType, FolderOpen, Plus, Upload, X } from "lucide-react";
 
 import { useTranslations } from "next-intl";
 import { useCallback, useMemo, useRef, useState } from "react";
 import { useDropzone } from "react-dropzone";
 import { toast } from "sonner";
 import { uploadDocumentMutationAtom } from "@/atoms/documents/document-mutation.atoms";
-import { SummaryConfig } from "@/components/assistant-ui/connector-popup/components/summary-config";
 import {
 	Accordion,
 	AccordionContent,
 	AccordionItem,
 	AccordionTrigger,
 } from "@/components/ui/accordion";
-import { Alert, AlertDescription } from "@/components/ui/alert";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
 import {
 	DropdownMenu,
 	DropdownMenuContent,
@@ -27,7 +24,6 @@ import {
 } from "@/components/ui/dropdown-menu";
 import { Label } from "@/components/ui/label";
 import { Progress } from "@/components/ui/progress";
-import { Separator } from "@/components/ui/separator";
 import { Spinner } from "@/components/ui/spinner";
 import { Switch } from "@/components/ui/switch";
 import { documentsApiService } from "@/lib/apis/documents-api.service";
@@ -36,7 +32,6 @@ import {
 	trackDocumentUploadStarted,
 	trackDocumentUploadSuccess,
 } from "@/lib/posthog/events";
-import { GridPattern } from "./GridPattern";
 
 interface SelectedFolder {
 	path: string;
@@ -128,13 +123,12 @@ interface FileWithId {
 	file: File;
 }
 
-const cardClass = "border border-border bg-slate-400/5 dark:bg-white/5";
-
-// Upload limits — files are sent in batches of 5 to avoid proxy timeouts
 const MAX_FILES = 50;
 const MAX_TOTAL_SIZE_MB = 200;
 const MAX_TOTAL_SIZE_BYTES = MAX_TOTAL_SIZE_MB * 1024 * 1024;
 
+const toggleRowClass = "flex items-center justify-between rounded-lg bg-slate-400/5 dark:bg-white/5 p-3";
+
 export function DocumentUploadTab({
 	searchSpaceId,
 	onSuccess,
@@ -198,7 +192,7 @@ export function DocumentUploadTab({
 	const { getRootProps, getInputProps, isDragActive } = useDropzone({
 		onDrop,
 		accept: acceptedFileTypes,
-		maxSize: 50 * 1024 * 1024, // 50MB per file
+		maxSize: 50 * 1024 * 1024,
 		noClick: isElectron,
 		disabled: files.length >= MAX_FILES,
 	});
@@ -270,6 +264,8 @@ export function DocumentUploadTab({
 		(MAX_TOTAL_SIZE_BYTES - totalFileSize) / (1024 * 1024)
 	).toFixed(1);
 
+	const hasContent = files.length > 0 || selectedFolder !== null;
+
 	const handleAccordionChange = useCallback(
 		(value: string) => {
 			setAccordionValue(value);
@@ -307,7 +303,7 @@ export function DocumentUploadTab({
 				});
 				toast.success(`Watching folder: ${selectedFolder.name}`);
 			} else {
-				toast.success(`Indexing folder: ${selectedFolder.name}`);
+				toast.success(`Syncing folder: ${selectedFolder.name}`);
 			}
 
 			setSelectedFolder(null);
@@ -355,139 +351,180 @@ export function DocumentUploadTab({
 		);
 	};
 
-	return (
-		<div className="space-y-3 sm:space-y-6 max-w-4xl mx-auto pt-0">
-			<Alert className="border border-border bg-slate-400/5 dark:bg-white/5">
-				<Info className="h-4 w-4 shrink-0 mt-0.5" />
-				<AlertDescription className="text-xs sm:text-sm leading-relaxed pt-0.5">
-					{t("file_size_limit")}{" "}
-					{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}
-				</AlertDescription>
-			</Alert>
+	const renderBrowseButton = (options?: { compact?: boolean; fullWidth?: boolean }) => {
+		const { compact, fullWidth } = options ?? {};
+		if (isFileCountLimitReached) return null;
 
-		<Card className={`relative overflow-hidden ${cardClass}`}>
-			<div className="absolute inset-0 [mask-image:radial-gradient(ellipse_at_center,white,transparent)] opacity-30">
-				<GridPattern />
-			</div>
-			<CardContent className="p-4 sm:p-10 relative z-10">
-				<div
-					{...getRootProps()}
-					className={`flex flex-col items-center justify-center min-h-[200px] sm:min-h-[300px] border-2 border-dashed rounded-lg transition-colors ${
-						isFileCountLimitReached || isSizeLimitReached
-							? "border-destructive/50 bg-destructive/5 cursor-not-allowed"
-							: "border-border hover:border-primary/50 cursor-pointer"
-					}`}
-				>
-					<input
-						{...getInputProps()}
-						ref={fileInputRef}
-						className="hidden"
-						onClick={handleFileInputClick}
-					/>
-					{isFileCountLimitReached ? (
-						<div className="flex flex-col items-center gap-2 sm:gap-4 text-center px-4">
-							<Upload className="h-8 w-8 sm:h-12 sm:w-12 text-destructive/70" />
-							<div>
-								<p className="text-sm sm:text-lg font-medium text-destructive">
-									{t("file_limit_reached")}
-								</p>
-								<p className="text-xs sm:text-sm text-muted-foreground mt-1">
-									{t("file_limit_reached_desc", { max: MAX_FILES })}
-								</p>
+		const sizeClass = compact ? "h-7" : "h-8";
+		const widthClass = fullWidth ? "w-full" : "";
+
+		if (isElectron) {
+			return (
+				<DropdownMenu>
+					<DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
+						<Button variant="secondary" size="sm" className={`text-xs gap-1 ${sizeClass} ${widthClass}`}>
+							Browse
+							<ChevronDown className="h-3 w-3 opacity-60" />
+						</Button>
+					</DropdownMenuTrigger>
+					<DropdownMenuContent align="center" onClick={(e) => e.stopPropagation()}>
+						<DropdownMenuItem onClick={handleBrowseFiles}>
+							<FileIcon className="h-4 w-4 mr-2" />
+							Files
+						</DropdownMenuItem>
+						<DropdownMenuItem onClick={handleBrowseFolder}>
+							<FolderOpen className="h-4 w-4 mr-2" />
+							Folder
+						</DropdownMenuItem>
+					</DropdownMenuContent>
+				</DropdownMenu>
+			);
+		}
+
+		return (
+			<Button
+				variant="secondary"
+				size="sm"
+				className={`text-xs ${sizeClass} ${widthClass}`}
+				onClick={(e) => {
+					e.stopPropagation();
+					e.preventDefault();
+					fileInputRef.current?.click();
+				}}
+			>
+				{t("browse_files")}
+			</Button>
+		);
+	};
+
+	return (
+		<div className="space-y-2 w-full mx-auto">
+			{/* Hidden file input for mobile browse */}
+			<input
+				{...getInputProps()}
+				ref={fileInputRef}
+				className="hidden"
+				onClick={handleFileInputClick}
+			/>
+
+			{/* MOBILE DROP ZONE */}
+			<div className="sm:hidden">
+				{hasContent ? (
+					!selectedFolder && !isFileCountLimitReached && (
+						isElectron ? (
+							<div className="w-full">
+								{renderBrowseButton({ compact: true, fullWidth: true })}
 							</div>
-						</div>
-					) : isDragActive ? (
-						<div className="flex flex-col items-center gap-2 sm:gap-4">
-							<Upload className="h-8 w-8 sm:h-12 sm:w-12 text-primary" />
-							<p className="text-sm sm:text-lg font-medium text-primary">{t("drop_files")}</p>
-						</div>
-					) : (
-						<div className="flex flex-col items-center gap-2 sm:gap-4">
-							<Upload className="h-8 w-8 sm:h-12 sm:w-12 text-muted-foreground" />
-							<div className="text-center">
-								<p className="text-sm sm:text-lg font-medium">{t("drag_drop")}</p>
-								<p className="text-xs sm:text-sm text-muted-foreground mt-1">{t("or_browse")}</p>
-							</div>
-							{files.length > 0 && (
-								<p className="text-xs text-muted-foreground">
-									{t("remaining_capacity", { files: remainingFiles, sizeMB: remainingSizeMB })}
-								</p>
-							)}
-						</div>
-					)}
-				{!isFileCountLimitReached && (
-					<div className="mt-2 sm:mt-4">
-						{isElectron ? (
-							<DropdownMenu>
-								<DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
-									<Button variant="secondary" size="sm" className="text-xs sm:text-sm gap-1">
-										{t("browse_files")}
-										<ChevronDown className="h-3 w-3 opacity-60" />
-									</Button>
-								</DropdownMenuTrigger>
-								<DropdownMenuContent align="center" onClick={(e) => e.stopPropagation()}>
-									<DropdownMenuItem onClick={handleBrowseFiles}>
-										<FileIcon className="h-4 w-4 mr-2" />
-										Files
-									</DropdownMenuItem>
-									<DropdownMenuItem onClick={handleBrowseFolder}>
-										<FolderOpen className="h-4 w-4 mr-2" />
-										Folder
-									</DropdownMenuItem>
-								</DropdownMenuContent>
-							</DropdownMenu>
 						) : (
 							<Button
-								variant="secondary"
+								variant="outline"
 								size="sm"
-								className="text-xs sm:text-sm"
-								onClick={(e) => {
-									e.stopPropagation();
-									e.preventDefault();
-									fileInputRef.current?.click();
-								}}
+								className="w-full text-xs h-8 gap-1.5 border-dashed border-muted-foreground/30"
+								onClick={() => fileInputRef.current?.click()}
 							>
-								{t("browse_files")}
+								<Plus className="h-3.5 w-3.5" />
+								Add more files
 							</Button>
+						)
+					)
+				) : (
+					<div
+						className="flex flex-col items-center gap-3 py-6 px-4 cursor-pointer"
+						onClick={() => {
+							if (!isElectron) fileInputRef.current?.click();
+						}}
+					>
+						<Upload className="h-7 w-7 text-muted-foreground" />
+						<div className="text-center space-y-1">
+							<p className="text-sm font-medium">
+								{isElectron ? "Select files or folder" : "Tap to select files"}
+							</p>
+							<p className="text-xs text-muted-foreground">
+								{t("file_size_limit")}{" "}
+								{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}
+							</p>
+						</div>
+						{isElectron && (
+							<div className="w-full mt-1" onClick={(e) => e.stopPropagation()}>
+								{renderBrowseButton({ fullWidth: true })}
+							</div>
 						)}
 					</div>
 				)}
-				</div>
-			</CardContent>
-		</Card>
+			</div>
 
-		{selectedFolder && (
-			<Card className={cardClass}>
-				<CardHeader className="p-4 sm:p-6">
-					<div className="flex items-center justify-between gap-2">
-						<div className="flex items-center gap-3 min-w-0 flex-1">
-							<FolderOpen className="h-5 w-5 text-primary flex-shrink-0" />
-							<div className="min-w-0 flex-1">
-								<CardTitle className="text-base sm:text-lg truncate">
-									{selectedFolder.name}
-								</CardTitle>
-								<CardDescription className="text-xs sm:text-sm truncate">
-									{selectedFolder.path}
-								</CardDescription>
-							</div>
+			{/* DESKTOP DROP ZONE */}
+			<div
+				{...getRootProps()}
+				className={`hidden sm:block border-2 border-dashed rounded-lg transition-colors ${
+					isFileCountLimitReached || isSizeLimitReached
+						? "border-destructive/50 bg-destructive/5 cursor-not-allowed"
+						: "border-muted-foreground/30 hover:border-foreground/70 cursor-pointer"
+				} ${hasContent ? "p-3" : "py-20 px-4"}`}
+			>
+				{hasContent ? (
+					<div className="flex items-center gap-3">
+						<Upload className="h-4 w-4 text-muted-foreground shrink-0" />
+						<span className="text-xs text-muted-foreground flex-1 truncate">
+							{isDragActive
+								? t("drop_files")
+								: isFileCountLimitReached
+									? t("file_limit_reached")
+									: t("remaining_capacity", { files: remainingFiles, sizeMB: remainingSizeMB })}
+						</span>
+						{renderBrowseButton({ compact: true })}
+					</div>
+				) : isFileCountLimitReached ? (
+					<div className="flex flex-col items-center gap-2 text-center">
+						<Upload className="h-8 w-8 text-destructive/70" />
+						<p className="text-sm font-medium text-destructive">{t("file_limit_reached")}</p>
+						<p className="text-xs text-muted-foreground">
+							{t("file_limit_reached_desc", { max: MAX_FILES })}
+						</p>
+					</div>
+				) : isDragActive ? (
+					<div className="flex flex-col items-center gap-2">
+						<Upload className="h-8 w-8 text-primary" />
+						<p className="text-sm font-medium text-primary">{t("drop_files")}</p>
+					</div>
+				) : (
+					<div className="flex flex-col items-center gap-2">
+						<Upload className="h-8 w-8 text-muted-foreground" />
+						<p className="text-sm font-medium">{t("drag_drop")}</p>
+						<p className="text-xs text-muted-foreground text-center">
+							{t("file_size_limit")}{" "}
+							{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}
+						</p>
+						<div className="mt-1">{renderBrowseButton()}</div>
+					</div>
+				)}
+			</div>
+
+			{/* FOLDER SELECTED */}
+			{selectedFolder && (
+				<div className="rounded-lg border border-border p-3 space-y-2">
+					<div className="flex items-center gap-2">
+						<FolderOpen className="h-4 w-4 text-primary shrink-0" />
+						<div className="min-w-0 flex-1">
+							<p className="text-sm font-medium truncate">{selectedFolder.name}</p>
+							<p className="text-xs text-muted-foreground truncate">{selectedFolder.path}</p>
 						</div>
 						<Button
 							variant="ghost"
 							size="icon"
-							className="h-8 w-8 shrink-0"
+							className="h-7 w-7 shrink-0"
 							onClick={() => setSelectedFolder(null)}
 							disabled={folderSubmitting}
 						>
-							<X className="h-4 w-4" />
+							<X className="h-3.5 w-3.5" />
 						</Button>
 					</div>
-				</CardHeader>
-				<CardContent className="p-4 sm:p-6 pt-0 space-y-4">
-					<div className="flex items-center justify-between rounded-lg border border-border p-3">
-						<Label htmlFor="watch-folder-toggle" className="flex flex-col gap-1 cursor-pointer">
+
+					<div className={toggleRowClass}>
+						<Label htmlFor="watch-folder-toggle" className="flex flex-col gap-0.5 cursor-pointer">
 							<span className="text-sm font-medium">Watch folder</span>
 							<span className="text-xs text-muted-foreground font-normal">
-								Automatically sync changes when files are added, edited, or removed
+								Auto-sync when files change
 							</span>
 						</Label>
 						<Switch
@@ -497,150 +534,133 @@ export function DocumentUploadTab({
 						/>
 					</div>
 
-					<SummaryConfig enabled={shouldSummarize} onEnabledChange={setShouldSummarize} />
+					<div className={toggleRowClass}>
+						<div className="space-y-0.5">
+							<p className="font-medium text-sm">Enable AI Summary</p>
+							<p className="text-xs text-muted-foreground">
+								Improves search quality but adds latency
+							</p>
+						</div>
+						<Switch checked={shouldSummarize} onCheckedChange={setShouldSummarize} />
+					</div>
 
 					<Button
-						className="w-full py-3 sm:py-6 text-xs sm:text-base font-medium"
+						className="w-full relative"
 						onClick={handleFolderSubmit}
 						disabled={folderSubmitting}
 					>
-						{folderSubmitting ? (
-							<span className="flex items-center gap-2">
+						<span className={folderSubmitting ? "invisible" : ""}>
+							{watchFolder ? "Sync & Watch for Changes" : "Sync Folder"}
+						</span>
+						{folderSubmitting && (
+							<span className="absolute inset-0 flex items-center justify-center">
 								<Spinner size="sm" />
-								Processing...
-							</span>
-						) : (
-							<span className="flex items-center gap-2">
-								<CheckCircle2 className="h-4 w-4 sm:h-5 sm:w-5" />
-								{watchFolder ? "Watch & Index Folder" : "Index Folder"}
 							</span>
 						)}
 					</Button>
-				</CardContent>
-			</Card>
-		)}
-
-			{files.length > 0 && (
-				<Card className={cardClass}>
-					<CardHeader className="p-4 sm:p-6">
-						<div className="flex items-center justify-between gap-2">
-							<div className="min-w-0 flex-1">
-								<CardTitle className="text-base sm:text-2xl">
-									{t("selected_files", { count: files.length })}
-								</CardTitle>
-								<CardDescription className="text-xs sm:text-sm">
-									{t("total_size")}: {formatFileSize(totalFileSize)}
-								</CardDescription>
-							</div>
-							<Button
-								variant="outline"
-								size="sm"
-								className="text-xs sm:text-sm shrink-0"
-								onClick={() => setFiles([])}
-								disabled={isUploading}
-							>
-								{t("clear_all")}
-							</Button>
-						</div>
-					</CardHeader>
-					<CardContent className="p-4 sm:p-6 pt-0">
-						<div className="space-y-2 sm:space-y-3 max-h-[250px] sm:max-h-[400px] overflow-y-auto">
-							{files.map((entry) => (
-								<div
-									key={entry.id}
-									className={`flex items-center justify-between p-2 sm:p-4 rounded-lg border border-border ${cardClass} hover:bg-slate-400/10 dark:hover:bg-white/10 transition-colors`}
-								>
-									<div className="flex items-center gap-3 flex-1 min-w-0">
-										<FileType className="h-5 w-5 text-muted-foreground flex-shrink-0" />
-										<div className="flex-1 min-w-0">
-											<p className="text-sm sm:text-base font-medium truncate">{entry.file.name}</p>
-											<div className="flex items-center gap-2 mt-1">
-												<Badge variant="secondary" className="text-xs">
-													{formatFileSize(entry.file.size)}
-												</Badge>
-												<Badge variant="outline" className="text-xs">
-													{entry.file.type || "Unknown type"}
-												</Badge>
-											</div>
-										</div>
-									</div>
-									<Button
-										variant="ghost"
-										size="icon"
-										onClick={() => setFiles((prev) => prev.filter((e) => e.id !== entry.id))}
-										disabled={isUploading}
-										className="h-8 w-8"
-									>
-										<X className="h-4 w-4" />
-									</Button>
-								</div>
-							))}
-						</div>
-
-						{isUploading && (
-							<div className="mt-3 sm:mt-6 space-y-2 sm:space-y-3">
-								<Separator className="bg-border" />
-								<div className="space-y-2">
-									<div className="flex items-center justify-between text-xs sm:text-sm">
-										<span>{t("uploading_files")}</span>
-										<span>{Math.round(uploadProgress)}%</span>
-									</div>
-									<Progress value={uploadProgress} className="h-2" />
-								</div>
-							</div>
-						)}
-
-						<div className="mt-3 sm:mt-6">
-							<SummaryConfig enabled={shouldSummarize} onEnabledChange={setShouldSummarize} />
-						</div>
-
-						<div className="mt-3 sm:mt-6">
-							<Button
-								className="w-full py-3 sm:py-6 text-xs sm:text-base font-medium"
-								onClick={handleUpload}
-								disabled={isUploading || files.length === 0}
-							>
-								{isUploading ? (
-									<span className="flex items-center gap-2">
-										<Spinner size="sm" />
-										{t("uploading")}
-									</span>
-								) : (
-									<span className="flex items-center gap-2">
-										<CheckCircle2 className="h-4 w-4 sm:h-5 sm:w-5" />
-										{t("upload_button", { count: files.length })}
-									</span>
-								)}
-							</Button>
-						</div>
-					</CardContent>
-				</Card>
+				</div>
 			)}
 
+			{/* FILES SELECTED */}
+			{files.length > 0 && (
+				<div className="rounded-lg border border-border p-3 space-y-2">
+					<div className="flex items-center justify-between">
+						<p className="text-sm font-medium">
+							{t("selected_files", { count: files.length })} &middot; {formatFileSize(totalFileSize)}
+						</p>
+						<Button
+							variant="ghost"
+							size="sm"
+							className="h-7 text-xs text-muted-foreground hover:text-foreground"
+							onClick={() => setFiles([])}
+							disabled={isUploading}
+						>
+							{t("clear_all")}
+						</Button>
+					</div>
+
+					<div className="max-h-[160px] sm:max-h-[200px] overflow-y-auto -mx-1">
+						{files.map((entry) => (
+							<div
+								key={entry.id}
+								className="flex items-center gap-2 py-1.5 px-2 rounded-md hover:bg-slate-400/5 dark:hover:bg-white/5 group"
+							>
+								<FileType className="h-4 w-4 text-muted-foreground shrink-0" />
+								<span className="text-sm truncate flex-1 min-w-0">{entry.file.name}</span>
+								<span className="text-xs text-muted-foreground shrink-0">
+									{formatFileSize(entry.file.size)}
+								</span>
+								<Button
+									variant="ghost"
+									size="icon"
+									className="h-6 w-6 shrink-0"
+									onClick={() => setFiles((prev) => prev.filter((e) => e.id !== entry.id))}
+									disabled={isUploading}
+								>
+									<X className="h-3 w-3" />
+								</Button>
+							</div>
+						))}
+					</div>
+
+					{isUploading && (
+						<div className="space-y-1">
+							<div className="flex items-center justify-between text-xs">
+								<span>{t("uploading_files")}</span>
+								<span>{Math.round(uploadProgress)}%</span>
+							</div>
+							<Progress value={uploadProgress} className="h-1.5" />
+						</div>
+					)}
+
+					<div className={toggleRowClass}>
+						<div className="space-y-0.5">
+							<p className="font-medium text-sm">Enable AI Summary</p>
+							<p className="text-xs text-muted-foreground">
+								Improves search quality but adds latency
+							</p>
+						</div>
+						<Switch checked={shouldSummarize} onCheckedChange={setShouldSummarize} />
+					</div>
+
+					<Button
+						className="w-full"
+						onClick={handleUpload}
+						disabled={isUploading || files.length === 0}
+					>
+						{isUploading ? (
+							<span className="flex items-center gap-2">
+								<Spinner size="sm" />
+								{t("uploading")}
+							</span>
+						) : (
+							<span className="flex items-center gap-2">
+								<CheckCircle2 className="h-4 w-4" />
+								{t("upload_button", { count: files.length })}
+							</span>
+						)}
+					</Button>
+				</div>
+			)}
+
+			{/* SUPPORTED FORMATS */}
 			<Accordion
 				type="single"
 				collapsible
 				value={accordionValue}
 				onValueChange={handleAccordionChange}
-				className={`w-full ${cardClass} border border-border rounded-lg mb-0`}
+				className="w-full"
 			>
-				<AccordionItem value="supported-file-types" className="border-0">
-					<AccordionTrigger className="px-3 sm:px-6 py-3 sm:py-4 hover:no-underline !items-center [&>svg]:!translate-y-0">
-						<div className="flex items-center gap-2 flex-1">
-							<div className="text-left min-w-0">
-								<div className="font-semibold text-sm sm:text-base">
-									{t("supported_file_types")}
-								</div>
-								<div className="text-xs sm:text-sm text-muted-foreground font-normal">
-									{t("file_types_desc")}
-								</div>
-							</div>
-						</div>
+				<AccordionItem value="supported-file-types" className="border border-border rounded-lg">
+					<AccordionTrigger className="px-3 py-2.5 hover:no-underline !items-center [&>svg]:!translate-y-0">
+						<span className="text-xs sm:text-sm text-muted-foreground font-normal">
+							{t("supported_file_types")}
+						</span>
 					</AccordionTrigger>
-					<AccordionContent className="px-3 sm:px-6 pb-3 sm:pb-6">
-						<div className="flex flex-wrap gap-2">
+					<AccordionContent className="px-3 pb-3">
+						<div className="flex flex-wrap gap-1">
 							{supportedExtensions.map((ext) => (
-								<Badge key={ext} variant="outline" className="text-xs">
+								<Badge key={ext} variant="outline" className="text-[10px] px-1.5 py-0">
 									{ext}
 								</Badge>
 							))}
diff --git a/surfsense_web/contracts/enums/connectorIcons.tsx b/surfsense_web/contracts/enums/connectorIcons.tsx
index 2e609b060..ab71d58b5 100644
--- a/surfsense_web/contracts/enums/connectorIcons.tsx
+++ b/surfsense_web/contracts/enums/connectorIcons.tsx
@@ -126,6 +126,8 @@ export const getConnectorIcon = (connectorType: EnumConnectorName | string, clas
 			return <Microscope {...iconProps} />;
 		case "DEEPEST":
 			return <Telescope {...iconProps} />;
+		case "LOCAL_FOLDER_FILE":
+			return null;
 		default:
 			return <Search {...iconProps} />;
 	}

From 44e39792da6fc7a35edbe8ae1cb68807e4ac3b3f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 04:14:28 +0530
Subject: [PATCH 37/70] feat: assign folder_id to documents before indexing to
 ensure correct folder visibility during processing

---
 .../local_folder_indexer.py                   | 37 ++++++++++++-------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index a3281eaea..041df71fc 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -719,6 +719,21 @@ async def index_local_folder(
             }
             documents = await pipeline.prepare_for_indexing(connector_docs)
 
+            # Assign folder_id immediately so docs appear in the correct
+            # folder while still pending/processing (visible via Zero sync).
+            for document in documents:
+                cd = doc_map.get(document.unique_identifier_hash)
+                if cd is None:
+                    continue
+                rel_path = (cd.metadata or {}).get("file_path", "")
+                parent_dir = str(Path(rel_path).parent) if rel_path else ""
+                if parent_dir == ".":
+                    parent_dir = ""
+                document.folder_id = folder_mapping.get(
+                    parent_dir, folder_mapping.get("")
+                )
+            await session.commit()
+
             llm = await get_user_long_context_llm(session, user_id, search_space_id)
 
             for document in documents:
@@ -732,17 +747,9 @@ async def index_local_folder(
                 if DocumentStatus.is_state(result.status, DocumentStatus.READY):
                     indexed_count += 1
 
-                    # Assign folder_id and mtime post-pipeline
-                    rel_path = (connector_doc.metadata or {}).get("file_path", "")
-                    parent_dir = str(Path(rel_path).parent) if rel_path else ""
-                    if parent_dir == ".":
-                        parent_dir = ""
-                    fid = folder_mapping.get(parent_dir, folder_mapping.get(""))
-
                     unique_id = connector_doc.unique_id
                     mtime_info = file_meta_map.get(unique_id, {})
 
-                    result.folder_id = fid
                     doc_meta = dict(result.document_metadata or {})
                     doc_meta["mtime"] = mtime_info.get("mtime")
                     result.document_metadata = doc_meta
@@ -894,16 +901,18 @@ async def _index_single_file(
             return 0, 1, None
 
         db_doc = documents[0]
-        await pipeline.index(db_doc, connector_doc, llm)
 
-        # Post-pipeline: assign folder_id and mtime
-        await session.refresh(db_doc)
-        folder_id = None
+        # Assign folder_id before indexing so the doc appears in the
+        # correct folder while still pending/processing.
         if root_folder_id:
-            folder_id = await _resolve_folder_for_file(
+            db_doc.folder_id = await _resolve_folder_for_file(
                 session, rel_path, root_folder_id, search_space_id, user_id
             )
-        db_doc.folder_id = folder_id
+            await session.commit()
+
+        await pipeline.index(db_doc, connector_doc, llm)
+
+        await session.refresh(db_doc)
         doc_meta = dict(db_doc.document_metadata or {})
         doc_meta["mtime"] = mtime
         db_doc.document_metadata = doc_meta

From fe7fcaae5dada13d12bf5883b5722c54dcd5f425 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 04:16:19 +0530
Subject: [PATCH 38/70] feat: update folder deletion process to queue document
 deletions first and handle folder cleanup in Celery task

---
 .../app/routes/folders_routes.py              | 31 +++++++++----------
 .../app/tasks/celery_tasks/document_tasks.py  | 27 ++++++++++++----
 .../layout/ui/sidebar/DocumentsSidebar.tsx    |  7 ++++-
 3 files changed, 42 insertions(+), 23 deletions(-)

diff --git a/surfsense_backend/app/routes/folders_routes.py b/surfsense_backend/app/routes/folders_routes.py
index 6e524d4a4..2dc9bceac 100644
--- a/surfsense_backend/app/routes/folders_routes.py
+++ b/surfsense_backend/app/routes/folders_routes.py
@@ -367,7 +367,7 @@ async def delete_folder(
     session: AsyncSession = Depends(get_async_session),
     user: User = Depends(current_active_user),
 ):
-    """Delete a folder and cascade-delete subfolders. Documents are async-deleted via Celery."""
+    """Mark documents for deletion and dispatch Celery to delete docs first, then folders."""
     try:
         folder = await session.get(Folder, folder_id)
         if not folder:
@@ -399,30 +399,29 @@ async def delete_folder(
             )
             await session.commit()
 
-        await session.execute(Folder.__table__.delete().where(Folder.id == folder_id))
-        await session.commit()
+        try:
+            from app.tasks.celery_tasks.document_tasks import (
+                delete_folder_documents_task,
+            )
 
-        if document_ids:
-            try:
-                from app.tasks.celery_tasks.document_tasks import (
-                    delete_folder_documents_task,
-                )
-
-                delete_folder_documents_task.delay(document_ids)
-            except Exception as err:
+            delete_folder_documents_task.delay(
+                document_ids, folder_subtree_ids=list(subtree_ids)
+            )
+        except Exception as err:
+            if document_ids:
                 await session.execute(
                     Document.__table__.update()
                     .where(Document.id.in_(document_ids))
                     .values(status={"state": "ready"})
                 )
                 await session.commit()
-                raise HTTPException(
-                    status_code=503,
-                    detail="Folder deleted but document cleanup could not be queued. Documents have been restored.",
-                ) from err
+            raise HTTPException(
+                status_code=503,
+                detail="Could not queue folder deletion. Documents have been restored.",
+            ) from err
 
         return {
-            "message": "Folder deleted successfully",
+            "message": "Folder deletion started",
             "documents_queued_for_deletion": len(document_ids),
         }
 
diff --git a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
index 110f3deee..4701d9911 100644
--- a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
+++ b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
@@ -142,21 +142,30 @@ async def _delete_document_background(document_id: int) -> None:
     retry_backoff_max=300,
     max_retries=5,
 )
-def delete_folder_documents_task(self, document_ids: list[int]):
-    """Celery task to batch-delete documents orphaned by folder deletion."""
+def delete_folder_documents_task(
+    self,
+    document_ids: list[int],
+    folder_subtree_ids: list[int] | None = None,
+):
+    """Celery task to delete documents first, then the folder rows."""
     loop = asyncio.new_event_loop()
     asyncio.set_event_loop(loop)
     try:
-        loop.run_until_complete(_delete_folder_documents(document_ids))
+        loop.run_until_complete(
+            _delete_folder_documents(document_ids, folder_subtree_ids)
+        )
     finally:
         loop.close()
 
 
-async def _delete_folder_documents(document_ids: list[int]) -> None:
-    """Delete chunks in batches, then document rows for each orphaned document."""
+async def _delete_folder_documents(
+    document_ids: list[int],
+    folder_subtree_ids: list[int] | None = None,
+) -> None:
+    """Delete chunks in batches, then document rows, then folder rows."""
     from sqlalchemy import delete as sa_delete, select
 
-    from app.db import Chunk, Document
+    from app.db import Chunk, Document, Folder
 
     async with get_celery_session_maker()() as session:
         batch_size = 500
@@ -178,6 +187,12 @@ async def _delete_folder_documents(document_ids: list[int]) -> None:
                 await session.delete(doc)
                 await session.commit()
 
+        if folder_subtree_ids:
+            await session.execute(
+                sa_delete(Folder).where(Folder.id.in_(folder_subtree_ids))
+            )
+            await session.commit()
+
 
 @celery_app.task(
     name="delete_search_space_background",
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index f8b774d26..8dce68eeb 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -188,7 +188,12 @@ export function DocumentsSidebar({
 
 	const treeDocuments: DocumentNodeDoc[] = useMemo(() => {
 		const zeroDocs = (zeroAllDocs ?? [])
-			.filter((d) => d.title && d.title.trim() !== "")
+			.filter((d) => {
+				if (!d.title || d.title.trim() === "") return false;
+				const state = (d.status as { state?: string } | undefined)?.state;
+				if (state === "deleting") return false;
+				return true;
+			})
 			.map((d) => ({
 				id: d.id,
 				title: d.title,

From 9a65163fe4d89d35e6891015c1b46b555f11f321 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 09:20:44 +0530
Subject: [PATCH 39/70] feat: improve DocumentUploadTab UI with updated styles,
 enhanced file size limit messages

---
 .../components/sources/DocumentUploadTab.tsx  | 89 ++++++++++---------
 surfsense_web/messages/en.json                |  4 +-
 surfsense_web/messages/es.json                |  4 +-
 surfsense_web/messages/hi.json                |  4 +-
 surfsense_web/messages/pt.json                |  4 +-
 surfsense_web/messages/zh.json                |  4 +-
 6 files changed, 55 insertions(+), 54 deletions(-)

diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index 7176afae5..9a32e5a59 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAtom } from "jotai";
-import { CheckCircle2, ChevronDown, File as FileIcon, FileType, FolderOpen, Plus, Upload, X } from "lucide-react";
+import { ChevronDown, Dot, File as FileIcon, FolderOpen, Upload, X } from "lucide-react";
 
 import { useTranslations } from "next-intl";
 import { useCallback, useMemo, useRef, useState } from "react";
@@ -22,7 +22,6 @@ import {
 	DropdownMenuItem,
 	DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
-import { Label } from "@/components/ui/label";
 import { Progress } from "@/components/ui/progress";
 import { Spinner } from "@/components/ui/spinner";
 import { Switch } from "@/components/ui/switch";
@@ -362,12 +361,12 @@ export function DocumentUploadTab({
 			return (
 				<DropdownMenu>
 					<DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
-						<Button variant="secondary" size="sm" className={`text-xs gap-1 ${sizeClass} ${widthClass}`}>
+						<Button variant="ghost" size="sm" className={`text-xs gap-1 bg-neutral-700/50 hover:bg-neutral-600/50 ${sizeClass} ${widthClass}`}>
 							Browse
 							<ChevronDown className="h-3 w-3 opacity-60" />
 						</Button>
 					</DropdownMenuTrigger>
-					<DropdownMenuContent align="center" onClick={(e) => e.stopPropagation()}>
+					<DropdownMenuContent align="center" className="dark:bg-neutral-800" onClick={(e) => e.stopPropagation()}>
 						<DropdownMenuItem onClick={handleBrowseFiles}>
 							<FileIcon className="h-4 w-4 mr-2" />
 							Files
@@ -416,32 +415,31 @@ export function DocumentUploadTab({
 								{renderBrowseButton({ compact: true, fullWidth: true })}
 							</div>
 						) : (
-							<Button
-								variant="outline"
-								size="sm"
-								className="w-full text-xs h-8 gap-1.5 border-dashed border-muted-foreground/30"
+							<button
+								type="button"
+								className="w-full text-xs h-8 flex items-center justify-center gap-1.5 rounded-md border border-dashed border-muted-foreground/30 text-muted-foreground hover:text-foreground hover:border-foreground/50 transition-colors"
 								onClick={() => fileInputRef.current?.click()}
 							>
-								<Plus className="h-3.5 w-3.5" />
 								Add more files
-							</Button>
+							</button>
 						)
 					)
 				) : (
 					<div
-						className="flex flex-col items-center gap-3 py-6 px-4 cursor-pointer"
+						className="flex flex-col items-center gap-4 py-12 px-4 cursor-pointer"
 						onClick={() => {
 							if (!isElectron) fileInputRef.current?.click();
 						}}
 					>
-						<Upload className="h-7 w-7 text-muted-foreground" />
-						<div className="text-center space-y-1">
-							<p className="text-sm font-medium">
+						<Upload className="h-10 w-10 text-muted-foreground" />
+						<div className="text-center space-y-1.5">
+							<p className="text-base font-medium">
 								{isElectron ? "Select files or folder" : "Tap to select files"}
 							</p>
-							<p className="text-xs text-muted-foreground">
-								{t("file_size_limit")}{" "}
-								{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}
+							<p className="text-sm text-muted-foreground inline-flex items-center flex-wrap justify-center">
+								<span>{t("file_size_limit")}</span>
+								<Dot className="h-4 w-4 shrink-0" />
+								<span>{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}</span>
 							</p>
 						</div>
 						{isElectron && (
@@ -491,9 +489,10 @@ export function DocumentUploadTab({
 					<div className="flex flex-col items-center gap-2">
 						<Upload className="h-8 w-8 text-muted-foreground" />
 						<p className="text-sm font-medium">{t("drag_drop")}</p>
-						<p className="text-xs text-muted-foreground text-center">
-							{t("file_size_limit")}{" "}
-							{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}
+						<p className="text-xs text-muted-foreground text-center inline-flex items-center flex-wrap justify-center">
+							<span>{t("file_size_limit")}</span>
+							<Dot className="h-4 w-4 shrink-0" />
+							<span>{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}</span>
 						</p>
 						<div className="mt-1">{renderBrowseButton()}</div>
 					</div>
@@ -520,28 +519,29 @@ export function DocumentUploadTab({
 						</Button>
 					</div>
 
-					<div className={toggleRowClass}>
-						<Label htmlFor="watch-folder-toggle" className="flex flex-col gap-0.5 cursor-pointer">
-							<span className="text-sm font-medium">Watch folder</span>
-							<span className="text-xs text-muted-foreground font-normal">
-								Auto-sync when files change
-							</span>
-						</Label>
-						<Switch
-							id="watch-folder-toggle"
-							checked={watchFolder}
-							onCheckedChange={setWatchFolder}
-						/>
-					</div>
-
-					<div className={toggleRowClass}>
-						<div className="space-y-0.5">
-							<p className="font-medium text-sm">Enable AI Summary</p>
-							<p className="text-xs text-muted-foreground">
-								Improves search quality but adds latency
-							</p>
+					<div className="rounded-lg bg-slate-400/5 dark:bg-white/5 divide-y divide-border">
+						<div className="flex items-center justify-between p-3">
+							<div className="space-y-0.5">
+								<p className="font-medium text-sm">Watch folder</p>
+								<p className="text-xs text-muted-foreground">
+									Auto-sync when files change
+								</p>
+							</div>
+							<Switch
+								id="watch-folder-toggle"
+								checked={watchFolder}
+								onCheckedChange={setWatchFolder}
+							/>
+						</div>
+						<div className="flex items-center justify-between p-3">
+							<div className="space-y-0.5">
+								<p className="font-medium text-sm">Enable AI Summary</p>
+								<p className="text-xs text-muted-foreground">
+									Improves search quality but adds latency
+								</p>
+							</div>
+							<Switch checked={shouldSummarize} onCheckedChange={setShouldSummarize} />
 						</div>
-						<Switch checked={shouldSummarize} onCheckedChange={setShouldSummarize} />
 					</div>
 
 					<Button
@@ -585,7 +585,9 @@ export function DocumentUploadTab({
 								key={entry.id}
 								className="flex items-center gap-2 py-1.5 px-2 rounded-md hover:bg-slate-400/5 dark:hover:bg-white/5 group"
 							>
-								<FileType className="h-4 w-4 text-muted-foreground shrink-0" />
+								<span className="text-[10px] font-medium uppercase leading-none bg-muted px-1.5 py-0.5 rounded text-muted-foreground shrink-0">
+									{entry.file.name.split(".").pop() || "?"}
+								</span>
 								<span className="text-sm truncate flex-1 min-w-0">{entry.file.name}</span>
 								<span className="text-xs text-muted-foreground shrink-0">
 									{formatFileSize(entry.file.size)}
@@ -635,7 +637,6 @@ export function DocumentUploadTab({
 							</span>
 						) : (
 							<span className="flex items-center gap-2">
-								<CheckCircle2 className="h-4 w-4" />
 								{t("upload_button", { count: files.length })}
 							</span>
 						)}
@@ -649,7 +650,7 @@ export function DocumentUploadTab({
 				collapsible
 				value={accordionValue}
 				onValueChange={handleAccordionChange}
-				className="w-full"
+				className="w-full mt-5"
 			>
 				<AccordionItem value="supported-file-types" className="border border-border rounded-lg">
 					<AccordionTrigger className="px-3 py-2.5 hover:no-underline !items-center [&>svg]:!translate-y-0">
diff --git a/surfsense_web/messages/en.json b/surfsense_web/messages/en.json
index 4310bc707..3cafebfdd 100644
--- a/surfsense_web/messages/en.json
+++ b/surfsense_web/messages/en.json
@@ -376,8 +376,8 @@
 	"upload_documents": {
 		"title": "Upload Documents",
 		"subtitle": "Upload your files to make them searchable and accessible through AI-powered conversations.",
-		"file_size_limit": "Maximum file size: 50MB per file.",
-		"upload_limits": "Upload limit: {maxFiles} files, {maxSizeMB}MB total.",
+		"file_size_limit": "Maximum file size: 50MB per file",
+		"upload_limits": "Upload limit: {maxFiles} files, {maxSizeMB}MB total",
 		"drop_files": "Drop files here",
 		"drag_drop": "Drag & drop files here",
 		"or_browse": "or click to browse",
diff --git a/surfsense_web/messages/es.json b/surfsense_web/messages/es.json
index 36e627295..99314ee7d 100644
--- a/surfsense_web/messages/es.json
+++ b/surfsense_web/messages/es.json
@@ -376,8 +376,8 @@
 	"upload_documents": {
 		"title": "Subir documentos",
 		"subtitle": "Sube tus archivos para hacerlos buscables y accesibles a través de conversaciones con IA.",
-		"file_size_limit": "Tamaño máximo de archivo: 50 MB por archivo.",
-		"upload_limits": "Límite de subida: {maxFiles} archivos, {maxSizeMB} MB en total.",
+		"file_size_limit": "Tamaño máximo de archivo: 50 MB por archivo",
+		"upload_limits": "Límite de subida: {maxFiles} archivos, {maxSizeMB} MB en total",
 		"drop_files": "Suelta los archivos aquí",
 		"drag_drop": "Arrastra y suelta archivos aquí",
 		"or_browse": "o haz clic para explorar",
diff --git a/surfsense_web/messages/hi.json b/surfsense_web/messages/hi.json
index fd51acdc2..c11f43815 100644
--- a/surfsense_web/messages/hi.json
+++ b/surfsense_web/messages/hi.json
@@ -376,8 +376,8 @@
 	"upload_documents": {
 		"title": "दस्तावेज़ अपलोड करें",
 		"subtitle": "AI-संचालित बातचीत के माध्यम से अपनी फ़ाइलों को खोजने योग्य और सुलभ बनाने के लिए अपलोड करें।",
-		"file_size_limit": "अधिकतम फ़ाइल आकार: प्रति फ़ाइल 50MB।",
-		"upload_limits": "अपलोड सीमा: {maxFiles} फ़ाइलें, कुल {maxSizeMB}MB।",
+		"file_size_limit": "अधिकतम फ़ाइल आकार: प्रति फ़ाइल 50MB",
+		"upload_limits": "अपलोड सीमा: {maxFiles} फ़ाइलें, कुल {maxSizeMB}MB",
 		"drop_files": "फ़ाइलें यहां छोड़ें",
 		"drag_drop": "फ़ाइलें यहां खींचें और छोड़ें",
 		"or_browse": "या ब्राउज़ करने के लिए क्लिक करें",
diff --git a/surfsense_web/messages/pt.json b/surfsense_web/messages/pt.json
index e26499f90..d77aa0c22 100644
--- a/surfsense_web/messages/pt.json
+++ b/surfsense_web/messages/pt.json
@@ -376,8 +376,8 @@
 	"upload_documents": {
 		"title": "Enviar documentos",
 		"subtitle": "Envie seus arquivos para torná-los pesquisáveis e acessíveis através de conversas com IA.",
-		"file_size_limit": "Tamanho máximo do arquivo: 50 MB por arquivo.",
-		"upload_limits": "Limite de envio: {maxFiles} arquivos, {maxSizeMB} MB no total.",
+		"file_size_limit": "Tamanho máximo do arquivo: 50 MB por arquivo",
+		"upload_limits": "Limite de envio: {maxFiles} arquivos, {maxSizeMB} MB no total",
 		"drop_files": "Solte os arquivos aqui",
 		"drag_drop": "Arraste e solte arquivos aqui",
 		"or_browse": "ou clique para navegar",
diff --git a/surfsense_web/messages/zh.json b/surfsense_web/messages/zh.json
index 819432410..b72a44dbb 100644
--- a/surfsense_web/messages/zh.json
+++ b/surfsense_web/messages/zh.json
@@ -360,8 +360,8 @@
 	"upload_documents": {
 		"title": "上传文档",
 		"subtitle": "上传您的文件，使其可通过 AI 对话进行搜索和访问。",
-		"file_size_limit": "最大文件大小：每个文件 50MB。",
-		"upload_limits": "上传限制：最多 {maxFiles} 个文件，总大小不超过 {maxSizeMB}MB。",
+		"file_size_limit": "最大文件大小：每个文件 50MB",
+		"upload_limits": "上传限制：最多 {maxFiles} 个文件，总大小不超过 {maxSizeMB}MB",
 		"drop_files": "放下文件到这里",
 		"drag_drop": "拖放文件到这里",
 		"or_browse": "或点击浏览",

From e2ba5093140a30b93056e376baa082df7a5324cf Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 09:29:59 +0530
Subject: [PATCH 40/70] feat: enhance error handling in local folder indexing
 by adding rollback and refresh on IntegrityError

---
 .../local_folder_indexer.py                   | 21 +++++++++++++------
 .../components/documents/DocumentNode.tsx     |  4 ++--
 .../layout/ui/sidebar/DocumentsSidebar.tsx    |  8 +++++++
 surfsense_web/components/ui/context-menu.tsx  |  2 +-
 surfsense_web/components/ui/dropdown-menu.tsx |  2 +-
 5 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index 041df71fc..7f6a35d7f 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -19,7 +19,7 @@ from datetime import UTC, datetime
 from pathlib import Path
 
 from sqlalchemy import select
-from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.exc import IntegrityError, SQLAlchemyError
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.config import config
@@ -732,7 +732,12 @@ async def index_local_folder(
                 document.folder_id = folder_mapping.get(
                     parent_dir, folder_mapping.get("")
                 )
-            await session.commit()
+            try:
+                await session.commit()
+            except IntegrityError:
+                await session.rollback()
+                for document in documents:
+                    await session.refresh(document)
 
             llm = await get_user_long_context_llm(session, user_id, search_space_id)
 
@@ -905,10 +910,14 @@ async def _index_single_file(
         # Assign folder_id before indexing so the doc appears in the
         # correct folder while still pending/processing.
         if root_folder_id:
-            db_doc.folder_id = await _resolve_folder_for_file(
-                session, rel_path, root_folder_id, search_space_id, user_id
-            )
-            await session.commit()
+            try:
+                db_doc.folder_id = await _resolve_folder_for_file(
+                    session, rel_path, root_folder_id, search_space_id, user_id
+                )
+                await session.commit()
+            except IntegrityError:
+                await session.rollback()
+                await session.refresh(db_doc)
 
         await pipeline.index(db_doc, connector_doc, llm)
 
diff --git a/surfsense_web/components/documents/DocumentNode.tsx b/surfsense_web/components/documents/DocumentNode.tsx
index 7a3b3e0ca..dc92109b1 100644
--- a/surfsense_web/components/documents/DocumentNode.tsx
+++ b/surfsense_web/components/documents/DocumentNode.tsx
@@ -237,7 +237,7 @@ export const DocumentNode = React.memo(function DocumentNode({
 							</DropdownMenuItem>
 							{onExport && (
 								<DropdownMenuSub>
-									<DropdownMenuSubTrigger>
+									<DropdownMenuSubTrigger disabled={isProcessing}>
 										<Download className="mr-2 h-4 w-4" />
 										Export
 									</DropdownMenuSubTrigger>
@@ -277,7 +277,7 @@ export const DocumentNode = React.memo(function DocumentNode({
 					</ContextMenuItem>
 					{onExport && (
 						<ContextMenuSub>
-							<ContextMenuSubTrigger>
+							<ContextMenuSubTrigger disabled={isProcessing}>
 								<Download className="mr-2 h-4 w-4" />
 								Export
 							</ContextMenuSubTrigger>
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index 8dce68eeb..7aa518361 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -358,6 +358,14 @@ export function DocumentsSidebar({
 	const handleDeleteFolder = useCallback(async (folder: FolderDisplay) => {
 		if (!confirm(`Delete folder "${folder.name}" and all its contents?`)) return;
 		try {
+			const api = window.electronAPI;
+			if (api) {
+				const watchedFolders = await api.getWatchedFolders();
+				const matched = watchedFolders.find((wf) => wf.rootFolderId === folder.id);
+				if (matched) {
+					await api.removeWatchedFolder(matched.path);
+				}
+			}
 			await foldersApiService.deleteFolder(folder.id);
 			toast.success("Folder deleted");
 		} catch (e: unknown) {
diff --git a/surfsense_web/components/ui/context-menu.tsx b/surfsense_web/components/ui/context-menu.tsx
index 0d3c27a6b..f3d4063e2 100644
--- a/surfsense_web/components/ui/context-menu.tsx
+++ b/surfsense_web/components/ui/context-menu.tsx
@@ -47,7 +47,7 @@ function ContextMenuSubTrigger({
 			data-slot="context-menu-sub-trigger"
 			data-inset={inset}
 			className={cn(
-				"focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground flex cursor-default items-center rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[inset]:pl-8",
+				"focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground flex cursor-default items-center rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8",
 				className
 			)}
 			{...props}
diff --git a/surfsense_web/components/ui/dropdown-menu.tsx b/surfsense_web/components/ui/dropdown-menu.tsx
index 24b99467e..1584e0ea4 100644
--- a/surfsense_web/components/ui/dropdown-menu.tsx
+++ b/surfsense_web/components/ui/dropdown-menu.tsx
@@ -182,7 +182,7 @@ function DropdownMenuSubTrigger({
 			data-slot="dropdown-menu-sub-trigger"
 			data-inset={inset}
 			className={cn(
-				"focus:bg-neutral-200 focus:text-accent-foreground dark:focus:bg-neutral-700 data-[state=open]:bg-neutral-200 data-[state=open]:text-accent-foreground dark:data-[state=open]:bg-neutral-700 [&_svg:not([class*='text-'])]:text-muted-foreground flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+				"focus:bg-neutral-200 focus:text-accent-foreground dark:focus:bg-neutral-700 data-[state=open]:bg-neutral-200 data-[state=open]:text-accent-foreground dark:data-[state=open]:bg-neutral-700 [&_svg:not([class*='text-'])]:text-muted-foreground flex cursor-default items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden select-none data-[disabled]:pointer-events-none data-[disabled]:opacity-50 data-[inset]:pl-8 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
 				className
 			)}
 			{...props}

From 1fa8e1cc836564ba71b64d51f4b253f5b10ef919 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 10:02:36 +0530
Subject: [PATCH 41/70] feat: refactor folder indexing to support batch
 processing of multiple files, enhancing performance and error handling

---
 .../app/routes/documents_routes.py            |  38 ++---
 .../app/tasks/celery_tasks/document_tasks.py  | 116 ++++++++++++---
 .../local_folder_indexer.py                   | 132 ++++++++++++++++--
 .../test_local_folder_pipeline.py             |  10 +-
 surfsense_web/hooks/use-folder-sync.ts        |  73 ++++++----
 .../lib/apis/documents-api.service.ts         |   4 +-
 6 files changed, 293 insertions(+), 80 deletions(-)

diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index edb01d4cc..e6eed7836 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -1305,11 +1305,11 @@ class FolderIndexRequest(PydanticBaseModel):
     enable_summary: bool = False
 
 
-class FolderIndexFileRequest(PydanticBaseModel):
+class FolderIndexFilesRequest(PydanticBaseModel):
     folder_path: str
     folder_name: str
     search_space_id: int
-    target_file_path: str
+    target_file_paths: list[str]
     root_folder_id: int | None = None
     enable_summary: bool = False
 
@@ -1393,14 +1393,15 @@ async def folder_index(
     }
 
 
-@router.post("/documents/folder-index-file")
-async def folder_index_file(
-    request: FolderIndexFileRequest,
+@router.post("/documents/folder-index-files")
+async def folder_index_files(
+    request: FolderIndexFilesRequest,
     session: AsyncSession = Depends(get_async_session),
     user: User = Depends(current_active_user),
 ):
-    """Index a single file within a watched folder (chokidar trigger).
-    Validates that target_file_path is under folder_path.
+    """Index multiple files within a watched folder (batched chokidar trigger).
+    Validates that all target_file_paths are under folder_path.
+    Dispatches a single Celery task that processes them in parallel.
     """
     from app.config import config as app_config
 
@@ -1410,6 +1411,9 @@ async def folder_index_file(
             detail="Local folder indexing is only available in self-hosted mode",
         )
 
+    if not request.target_file_paths:
+        raise HTTPException(status_code=400, detail="target_file_paths must not be empty")
+
     await check_permission(
         session,
         user,
@@ -1420,13 +1424,14 @@ async def folder_index_file(
 
     from pathlib import Path
 
-    try:
-        Path(request.target_file_path).relative_to(request.folder_path)
-    except ValueError:
-        raise HTTPException(
-            status_code=400,
-            detail="target_file_path must be inside folder_path",
-        )
+    for fp in request.target_file_paths:
+        try:
+            Path(fp).relative_to(request.folder_path)
+        except ValueError:
+            raise HTTPException(
+                status_code=400,
+                detail=f"target_file_path {fp} must be inside folder_path",
+            )
 
     from app.tasks.celery_tasks.document_tasks import index_local_folder_task
 
@@ -1435,14 +1440,15 @@ async def folder_index_file(
         user_id=str(user.id),
         folder_path=request.folder_path,
         folder_name=request.folder_name,
-        target_file_path=request.target_file_path,
+        target_file_paths=request.target_file_paths,
         root_folder_id=request.root_folder_id,
         enable_summary=request.enable_summary,
     )
 
     return {
-        "message": "File indexing started",
+        "message": f"Batch indexing started for {len(request.target_file_paths)} file(s)",
         "status": "processing",
+        "file_count": len(request.target_file_paths),
     }
 
 
diff --git a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
index 4701d9911..16ac50967 100644
--- a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
+++ b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
@@ -1275,7 +1275,7 @@ def index_local_folder_task(
     file_extensions: list[str] | None = None,
     root_folder_id: int | None = None,
     enable_summary: bool = False,
-    target_file_path: str | None = None,
+    target_file_paths: list[str] | None = None,
 ):
     """Celery task to index a local folder. Config is passed directly — no connector row."""
     loop = asyncio.new_event_loop()
@@ -1292,7 +1292,7 @@ def index_local_folder_task(
                 file_extensions=file_extensions,
                 root_folder_id=root_folder_id,
                 enable_summary=enable_summary,
-                target_file_path=target_file_path,
+                target_file_paths=target_file_paths,
             )
         )
     finally:
@@ -1308,19 +1308,103 @@ async def _index_local_folder_async(
     file_extensions: list[str] | None = None,
     root_folder_id: int | None = None,
     enable_summary: bool = False,
-    target_file_path: str | None = None,
+    target_file_paths: list[str] | None = None,
 ):
-    """Run local folder indexing with a fresh DB session."""
+    """Run local folder indexing with notification + heartbeat."""
+    is_batch = bool(target_file_paths)
+    is_full_scan = not target_file_paths
+    file_count = len(target_file_paths) if target_file_paths else None
+
+    if is_batch:
+        doc_name = f"{folder_name} ({file_count} file{'s' if file_count != 1 else ''})"
+    else:
+        doc_name = folder_name
+
+    notification = None
+    heartbeat_task = None
+
     async with get_celery_session_maker()() as session:
-        await index_local_folder(
-            session=session,
-            search_space_id=search_space_id,
-            user_id=user_id,
-            folder_path=folder_path,
-            folder_name=folder_name,
-            exclude_patterns=exclude_patterns,
-            file_extensions=file_extensions,
-            root_folder_id=root_folder_id,
-            enable_summary=enable_summary,
-            target_file_path=target_file_path,
-        )
+        try:
+            notification = (
+                await NotificationService.document_processing.notify_processing_started(
+                    session=session,
+                    user_id=UUID(user_id),
+                    document_type="LOCAL_FOLDER_FILE",
+                    document_name=doc_name,
+                    search_space_id=search_space_id,
+                )
+            )
+            _start_heartbeat(notification.id)
+            heartbeat_task = asyncio.create_task(
+                _run_heartbeat_loop(notification.id)
+            )
+        except Exception:
+            logger.warning(
+                "Failed to create notification for local folder indexing",
+                exc_info=True,
+            )
+
+        async def _heartbeat_progress(completed_count: int) -> None:
+            """Refresh heartbeat and optionally update notification progress."""
+            if notification:
+                try:
+                    await NotificationService.document_processing.notify_processing_progress(
+                        session=session,
+                        notification=notification,
+                        stage="indexing",
+                        stage_message=f"Syncing files ({completed_count}/{file_count or '?'})",
+                    )
+                except Exception:
+                    pass
+
+        try:
+            indexed, skipped_or_failed, _rfid, err = await index_local_folder(
+                session=session,
+                search_space_id=search_space_id,
+                user_id=user_id,
+                folder_path=folder_path,
+                folder_name=folder_name,
+                exclude_patterns=exclude_patterns,
+                file_extensions=file_extensions,
+                root_folder_id=root_folder_id,
+                enable_summary=enable_summary,
+                target_file_paths=target_file_paths,
+                on_heartbeat_callback=_heartbeat_progress if (is_batch or is_full_scan) else None,
+            )
+
+            if notification:
+                try:
+                    if err:
+                        await NotificationService.document_processing.notify_processing_completed(
+                            session=session,
+                            notification=notification,
+                            error_message=err,
+                        )
+                    else:
+                        await NotificationService.document_processing.notify_processing_completed(
+                            session=session,
+                            notification=notification,
+                        )
+                except Exception:
+                    logger.warning(
+                        "Failed to update notification after local folder indexing",
+                        exc_info=True,
+                    )
+
+        except Exception as e:
+            logger.exception(f"Local folder indexing failed: {e}")
+            if notification:
+                try:
+                    await NotificationService.document_processing.notify_processing_completed(
+                        session=session,
+                        notification=notification,
+                        error_message=str(e)[:200],
+                    )
+                except Exception:
+                    pass
+            raise
+        finally:
+            if heartbeat_task:
+                heartbeat_task.cancel()
+            if notification:
+                _stop_heartbeat(notification.id)
diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index 7f6a35d7f..4ac8cc594 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -3,7 +3,7 @@ Local folder indexer.
 
 Indexes files from a local folder on disk. Supports:
 - Full-scan mode (startup reconciliation / manual trigger)
-- Single-file mode (chokidar real-time trigger)
+- Batch mode (chokidar real-time trigger, 1..N files)
 - Filesystem folder structure mirroring into DB Folder rows
 - Document versioning via create_version_snapshot
 - ETL-based file parsing for binary formats (PDF, DOCX, images, audio, etc.)
@@ -13,6 +13,7 @@ Config (folder_path, exclude_patterns, etc.) is passed in from the caller —
 no connector row is read.
 """
 
+import asyncio
 import os
 from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
@@ -34,6 +35,7 @@ from app.indexing_pipeline.document_hashing import compute_identifier_hash
 from app.indexing_pipeline.indexing_pipeline_service import IndexingPipelineService
 from app.services.llm_service import get_user_long_context_llm
 from app.services.task_logging_service import TaskLoggingService
+from app.tasks.celery_tasks import get_celery_session_maker
 from app.utils.document_versioning import create_version_snapshot
 
 from .base import (
@@ -497,14 +499,15 @@ async def index_local_folder(
     file_extensions: list[str] | None = None,
     root_folder_id: int | None = None,
     enable_summary: bool = False,
-    target_file_path: str | None = None,
+    target_file_paths: list[str] | None = None,
     on_heartbeat_callback: HeartbeatCallbackType | None = None,
 ) -> tuple[int, int, int | None, str | None]:
     """Index files from a local folder.
 
     Supports two modes:
-    - Full scan (target_file_path=None): walks entire folder, handles new/changed/deleted files.
-    - Single-file (target_file_path set): processes only that file.
+    - Batch (target_file_paths set): processes 1..N files.
+      Single-file uses the caller's session; multi-file fans out with per-file sessions.
+    - Full scan (no target paths): walks entire folder, handles new/changed/deleted files.
 
     Returns (indexed_count, skipped_count, root_folder_id, error_or_warning_message).
     """
@@ -517,7 +520,7 @@ async def index_local_folder(
         metadata={
             "folder_path": folder_path,
             "user_id": str(user_id),
-            "target_file_path": target_file_path,
+            "target_file_paths_count": len(target_file_paths) if target_file_paths else None,
         },
     )
 
@@ -535,22 +538,47 @@ async def index_local_folder(
             exclude_patterns = DEFAULT_EXCLUDE_PATTERNS
 
         # ====================================================================
-        # SINGLE-FILE MODE
+        # BATCH MODE (1..N files)
         # ====================================================================
-        if target_file_path:
-            indexed, skipped, err = await _index_single_file(
-                session=session,
+        if target_file_paths:
+            if len(target_file_paths) == 1:
+                indexed, skipped, err = await _index_single_file(
+                    session=session,
+                    search_space_id=search_space_id,
+                    user_id=user_id,
+                    folder_path=folder_path,
+                    folder_name=folder_name,
+                    target_file_path=target_file_paths[0],
+                    enable_summary=enable_summary,
+                    root_folder_id=root_folder_id,
+                    task_logger=task_logger,
+                    log_entry=log_entry,
+                )
+                return indexed, skipped, root_folder_id, err
+
+            indexed, failed, err = await _index_batch_files(
                 search_space_id=search_space_id,
                 user_id=user_id,
                 folder_path=folder_path,
                 folder_name=folder_name,
-                target_file_path=target_file_path,
+                target_file_paths=target_file_paths,
                 enable_summary=enable_summary,
                 root_folder_id=root_folder_id,
-                task_logger=task_logger,
-                log_entry=log_entry,
+                on_progress_callback=on_heartbeat_callback,
             )
-            return indexed, skipped, root_folder_id, err
+            if err:
+                await task_logger.log_task_success(
+                    log_entry,
+                    f"Batch indexing: {indexed} indexed, {failed} failed",
+                    {"indexed": indexed, "failed": failed},
+                )
+            else:
+                await task_logger.log_task_success(
+                    log_entry,
+                    f"Batch indexing complete: {indexed} indexed",
+                    {"indexed": indexed, "failed": failed},
+                )
+            return indexed, failed, root_folder_id, err
 
         # ====================================================================
         # FULL-SCAN MODE
@@ -822,6 +850,84 @@ async def index_local_folder(
         return 0, 0, root_folder_id, str(e)
 
 
+BATCH_CONCURRENCY = 5
+
+
+async def _index_batch_files(
+    search_space_id: int,
+    user_id: str,
+    folder_path: str,
+    folder_name: str,
+    target_file_paths: list[str],
+    enable_summary: bool,
+    root_folder_id: int | None,
+    on_progress_callback: HeartbeatCallbackType | None = None,
+) -> tuple[int, int, str | None]:
+    """Process multiple files in parallel with bounded concurrency.
+
+    Each file gets its own DB session so they can run concurrently.
+    Returns (indexed_count, failed_count, error_summary_or_none).
+    """
+    semaphore = asyncio.Semaphore(BATCH_CONCURRENCY)
+    indexed = 0
+    failed = 0
+    errors: list[str] = []
+    lock = asyncio.Lock()
+    completed = 0
+
+    async def process_one(file_path: str) -> None:
+        nonlocal indexed, failed, completed
+        async with semaphore:
+            try:
+                async with get_celery_session_maker()() as file_session:
+                    task_logger = TaskLoggingService(file_session, search_space_id)
+                    log_entry = await task_logger.log_task_start(
+                        task_name="local_folder_indexing",
+                        source="local_folder_batch_indexing",
+                        message=f"Batch: indexing {Path(file_path).name}",
+                        metadata={"file_path": file_path},
+                    )
+                    ix, _sk, err = await _index_single_file(
+                        session=file_session,
+                        search_space_id=search_space_id,
+                        user_id=user_id,
+                        folder_path=folder_path,
+                        folder_name=folder_name,
+                        target_file_path=file_path,
+                        enable_summary=enable_summary,
+                        root_folder_id=root_folder_id,
+                        task_logger=task_logger,
+                        log_entry=log_entry,
+                    )
+                    async with lock:
+                        indexed += ix
+                        if err:
+                            failed += 1
+                            errors.append(f"{Path(file_path).name}: {err}")
+                        completed += 1
+                        if on_progress_callback and completed % BATCH_CONCURRENCY == 0:
+                            await on_progress_callback(completed)
+            except Exception as exc:
+                logger.exception(f"Batch: error processing {file_path}: {exc}")
+                async with lock:
+                    failed += 1
+                    completed += 1
+                    errors.append(f"{Path(file_path).name}: {exc}")
+
+    await asyncio.gather(*[process_one(fp) for fp in target_file_paths])
+
+    if on_progress_callback:
+        await on_progress_callback(completed)
+
+    error_summary = None
+    if errors:
+        error_summary = f"{failed} file(s) failed: " + "; ".join(errors[:5])
+        if len(errors) > 5:
+            error_summary += f" ... and {len(errors) - 5} more"
+
+    return indexed, failed, error_summary
+
+
 async def _index_single_file(
     session: AsyncSession,
     search_space_id: int,
diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index 154cc6e0e..6cc5655c4 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -215,7 +215,7 @@ class TestFullIndexer:
         db_search_space: SearchSpace,
         tmp_path: Path,
     ):
-        """I5: Single-file mode only processes the specified file."""
+        """I5: Batch mode with a single file only processes that file."""
         from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
 
         (tmp_path / "a.md").write_text("File A")
@@ -228,7 +228,7 @@ class TestFullIndexer:
             user_id=str(db_user.id),
             folder_path=str(tmp_path),
             folder_name="test-folder",
-            target_file_path=str(tmp_path / "b.md"),
+            target_file_paths=[str(tmp_path / "b.md")],
         )
         assert count == 1
 
@@ -507,7 +507,7 @@ class TestFolderMirroring:
             user_id=str(db_user.id),
             folder_path=str(tmp_path),
             folder_name="test-folder",
-            target_file_path=str(sub / "new.md"),
+            target_file_paths=[str(sub / "new.md")],
             root_folder_id=root_folder_id,
         )
         assert count == 1
@@ -546,7 +546,7 @@ class TestFolderMirroring:
         db_search_space: SearchSpace,
         tmp_path: Path,
     ):
-        """F7: Deleting the only file in a subfolder via single-file mode removes empty Folder rows."""
+        """F7: Deleting the only file in a subfolder via batch mode removes empty Folder rows."""
         from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
 
         sub = tmp_path / "notes" / "ephemeral"
@@ -578,7 +578,7 @@ class TestFolderMirroring:
             user_id=str(db_user.id),
             folder_path=str(tmp_path),
             folder_name="test-folder",
-            target_file_path=str(target),
+            target_file_paths=[str(target)],
             root_folder_id=root_folder_id,
         )
 
diff --git a/surfsense_web/hooks/use-folder-sync.ts b/surfsense_web/hooks/use-folder-sync.ts
index 59c061afb..a64add593 100644
--- a/surfsense_web/hooks/use-folder-sync.ts
+++ b/surfsense_web/hooks/use-folder-sync.ts
@@ -16,65 +16,82 @@ interface FileChangedEvent {
 }
 
 const DEBOUNCE_MS = 2000;
-interface QueueItem {
-	event: FileChangedEvent;
+
+interface BatchItem {
+	folderPath: string;
+	folderName: string;
+	searchSpaceId: number;
+	rootFolderId: number | null;
+	filePaths: string[];
 	ackIds: string[];
 }
 
 export function useFolderSync() {
-	const queueRef = useRef<QueueItem[]>([]);
+	const queueRef = useRef<BatchItem[]>([]);
 	const processingRef = useRef(false);
 	const debounceTimers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
-	const pendingByKey = useRef<Map<string, QueueItem>>(new Map());
+	const pendingByFolder = useRef<Map<string, BatchItem>>(new Map());
 	const isMountedRef = useRef(false);
 
 	async function processQueue() {
 		if (processingRef.current) return;
 		processingRef.current = true;
 		while (queueRef.current.length > 0) {
-			const item = queueRef.current.shift()!;
+			const batch = queueRef.current.shift()!;
 			try {
-				await documentsApiService.folderIndexFile(item.event.searchSpaceId, {
-					folder_path: item.event.folderPath,
-					folder_name: item.event.folderName,
-					search_space_id: item.event.searchSpaceId,
-					target_file_path: item.event.fullPath,
-					root_folder_id: item.event.rootFolderId,
+				await documentsApiService.folderIndexFiles(batch.searchSpaceId, {
+					folder_path: batch.folderPath,
+					folder_name: batch.folderName,
+					search_space_id: batch.searchSpaceId,
+					target_file_paths: batch.filePaths,
+					root_folder_id: batch.rootFolderId,
 				});
 				const api = typeof window !== "undefined" ? window.electronAPI : null;
-				if (api?.acknowledgeFileEvents && item.ackIds.length > 0) {
-					await api.acknowledgeFileEvents(item.ackIds);
+				if (api?.acknowledgeFileEvents && batch.ackIds.length > 0) {
+					await api.acknowledgeFileEvents(batch.ackIds);
 				}
 			} catch (err) {
-				console.error("[FolderSync] Failed to trigger re-index:", err);
+				console.error("[FolderSync] Failed to trigger batch re-index:", err);
 			}
 		}
 		processingRef.current = false;
 	}
 
 	function enqueueWithDebounce(event: FileChangedEvent) {
-		const key = `${event.folderPath}:${event.relativePath}`;
-		const existing = pendingByKey.current.get(key);
-		const ackSet = new Set(existing?.ackIds ?? []);
-		ackSet.add(event.id);
-		pendingByKey.current.set(key, {
-			event,
-			ackIds: Array.from(ackSet),
-		});
+		const folderKey = event.folderPath;
+		const existing = pendingByFolder.current.get(folderKey);
 
-		const existingTimeout = debounceTimers.current.get(key);
+		if (existing) {
+			const pathSet = new Set(existing.filePaths);
+			pathSet.add(event.fullPath);
+			existing.filePaths = Array.from(pathSet);
+			if (!existing.ackIds.includes(event.id)) {
+				existing.ackIds.push(event.id);
+			}
+		} else {
+			pendingByFolder.current.set(folderKey, {
+				folderPath: event.folderPath,
+				folderName: event.folderName,
+				searchSpaceId: event.searchSpaceId,
+				rootFolderId: event.rootFolderId,
+				filePaths: [event.fullPath],
+				ackIds: [event.id],
+			});
+		}
+
+		const existingTimeout = debounceTimers.current.get(folderKey);
 		if (existingTimeout) clearTimeout(existingTimeout);
 
 		const timeout = setTimeout(() => {
-			debounceTimers.current.delete(key);
-			const pending = pendingByKey.current.get(key);
+			debounceTimers.current.delete(folderKey);
+			const pending = pendingByFolder.current.get(folderKey);
 			if (!pending) return;
-			pendingByKey.current.delete(key);
+			pendingByFolder.current.delete(folderKey);
 			queueRef.current.push(pending);
 			processQueue();
 		}, DEBOUNCE_MS);
 
-		debounceTimers.current.set(key, timeout);
+		debounceTimers.current.set(folderKey, timeout);
 	}
 
 	useEffect(() => {
@@ -108,7 +125,7 @@ export function useFolderSync() {
 				clearTimeout(timeout);
 			}
 			debounceTimers.current.clear();
-			pendingByKey.current.clear();
+			pendingByFolder.current.clear();
 		};
 	}, []);
 }
diff --git a/surfsense_web/lib/apis/documents-api.service.ts b/surfsense_web/lib/apis/documents-api.service.ts
index e8b228d03..45d9f6dc8 100644
--- a/surfsense_web/lib/apis/documents-api.service.ts
+++ b/surfsense_web/lib/apis/documents-api.service.ts
@@ -400,8 +400,8 @@ class DocumentsApiService {
 		return baseApiService.post(`/api/v1/documents/folder-index`, undefined, { body });
 	};
 
-	folderIndexFile = async (searchSpaceId: number, body: { folder_path: string; folder_name: string; search_space_id: number; target_file_path: string; root_folder_id?: number | null; enable_summary?: boolean }) => {
-		return baseApiService.post(`/api/v1/documents/folder-index-file`, undefined, { body });
+	folderIndexFiles = async (searchSpaceId: number, body: { folder_path: string; folder_name: string; search_space_id: number; target_file_paths: string[]; root_folder_id?: number | null; enable_summary?: boolean }) => {
+		return baseApiService.post(`/api/v1/documents/folder-index-files`, undefined, { body });
 	};
 
 	getWatchedFolders = async (searchSpaceId: number) => {

From 2b9d79d44c00699253cbcab934e549c6c64b94cb Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 10:04:14 +0530
Subject: [PATCH 42/70] feat: add integration tests for batch processing of
 local folder indexing, covering multiple file scenarios and error handling

---
 .../test_local_folder_pipeline.py             | 130 +++++++++++++++++-
 1 file changed, 129 insertions(+), 1 deletion(-)

diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index 6cc5655c4..67254ec93 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -1,6 +1,7 @@
-"""Integration tests for local folder indexer — Tier 3 (I1-I5), Tier 4 (F1-F7), Tier 5 (P1)."""
+"""Integration tests for local folder indexer — Tier 3 (I1-I5), Tier 4 (F1-F7), Tier 5 (P1), Tier 6 (B1-B2)."""
 
 import os
+from contextlib import asynccontextmanager
 from pathlib import Path
 
 import pytest
@@ -24,6 +25,34 @@ UNIFIED_FIXTURES = (
 )
 
 
+class _FakeSessionMaker:
+    """Wraps an existing AsyncSession so ``async with factory()`` yields it
+    without closing it. Used to route batch-mode DB operations through the
+    test's savepoint-wrapped session."""
+
+    def __init__(self, session: AsyncSession):
+        self._session = session
+
+    def __call__(self):
+        @asynccontextmanager
+        async def _ctx():
+            yield self._session
+        return _ctx()
+
+
+@pytest.fixture
+def patched_batch_sessions(monkeypatch, db_session):
+    """Make ``_index_batch_files`` use the test session and run sequentially."""
+    monkeypatch.setattr(
+        "app.tasks.connector_indexers.local_folder_indexer.get_celery_session_maker",
+        lambda: _FakeSessionMaker(db_session),
+    )
+    monkeypatch.setattr(
+        "app.tasks.connector_indexers.local_folder_indexer.BATCH_CONCURRENCY",
+        1,
+    )
+
+
 # ====================================================================
 # Tier 3: Full Indexer Integration (I1-I5)
 # ====================================================================
@@ -597,6 +626,105 @@ class TestFolderMirroring:
         assert notes_after is None
 
 
+# ====================================================================
+# Tier 6: Batch Mode (B1-B2)
+# ====================================================================
+
+
+class TestBatchMode:
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_b1_batch_indexes_multiple_files(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+        patched_batch_sessions,
+    ):
+        """B1: Batch with 3 files indexes all of them."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "a.md").write_text("File A content")
+        (tmp_path / "b.md").write_text("File B content")
+        (tmp_path / "c.md").write_text("File C content")
+
+        count, failed, root_folder_id, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            target_file_paths=[
+                str(tmp_path / "a.md"),
+                str(tmp_path / "b.md"),
+                str(tmp_path / "c.md"),
+            ],
+        )
+
+        assert count == 3
+        assert failed == 0
+        assert err is None
+
+        docs = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
+                )
+            )
+        ).scalars().all()
+        assert len(docs) == 3
+        assert {d.title for d in docs} == {"a.md", "b.md", "c.md"}
+        assert all(
+            DocumentStatus.is_state(d.status, DocumentStatus.READY) for d in docs
+        )
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_b2_partial_failure(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+        patched_batch_sessions,
+    ):
+        """B2: One unreadable file fails gracefully; the other two still get indexed."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "good1.md").write_text("Good file one")
+        (tmp_path / "good2.md").write_text("Good file two")
+        (tmp_path / "bad.md").write_bytes(b"\x00binary garbage")
+
+        count, failed, _, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            target_file_paths=[
+                str(tmp_path / "good1.md"),
+                str(tmp_path / "bad.md"),
+                str(tmp_path / "good2.md"),
+            ],
+        )
+
+        assert count == 2
+        assert failed == 1
+        assert err is not None
+
+        docs = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
+                )
+            )
+        ).scalars().all()
+        assert len(docs) == 2
+        assert {d.title for d in docs} == {"good1.md", "good2.md"}
+
+
 # ====================================================================
 # Tier 5: Pipeline Integration (P1)
 # ====================================================================

From 19dfd9f90765d4021ac71c68b7bfd47e26e0ac61 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 10:13:46 +0530
Subject: [PATCH 43/70] feat: enhance folder synchronization by adding max wait
 time and batch size limits for processing file events

---
 surfsense_web/hooks/use-folder-sync.ts | 40 ++++++++++++++++++++------
 1 file changed, 31 insertions(+), 9 deletions(-)

diff --git a/surfsense_web/hooks/use-folder-sync.ts b/surfsense_web/hooks/use-folder-sync.ts
index a64add593..ef3326556 100644
--- a/surfsense_web/hooks/use-folder-sync.ts
+++ b/surfsense_web/hooks/use-folder-sync.ts
@@ -16,6 +16,8 @@ interface FileChangedEvent {
 }
 
 const DEBOUNCE_MS = 2000;
+const MAX_WAIT_MS = 10_000;
+const MAX_BATCH_SIZE = 50;
 
 interface BatchItem {
 	folderPath: string;
@@ -31,6 +33,7 @@ export function useFolderSync() {
 	const processingRef = useRef(false);
 	const debounceTimers = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());
 	const pendingByFolder = useRef<Map<string, BatchItem>>(new Map());
+	const firstEventTime = useRef<Map<string, number>>(new Map());
 	const isMountedRef = useRef(false);
 
 	async function processQueue() {
@@ -57,6 +60,23 @@ export function useFolderSync() {
 		processingRef.current = false;
 	}
 
+	function flushFolder(folderKey: string) {
+		debounceTimers.current.delete(folderKey);
+		firstEventTime.current.delete(folderKey);
+		const pending = pendingByFolder.current.get(folderKey);
+		if (!pending) return;
+		pendingByFolder.current.delete(folderKey);
+
+		for (let i = 0; i < pending.filePaths.length; i += MAX_BATCH_SIZE) {
+			queueRef.current.push({
+				...pending,
+				filePaths: pending.filePaths.slice(i, i + MAX_BATCH_SIZE),
+				ackIds: i === 0 ? pending.ackIds : [],
+			});
+		}
+		processQueue();
+	}
+
 	function enqueueWithDebounce(event: FileChangedEvent) {
 		const folderKey = event.folderPath;
 		const existing = pendingByFolder.current.get(folderKey);
@@ -77,20 +97,21 @@ export function useFolderSync() {
 				filePaths: [event.fullPath],
 				ackIds: [event.id],
 			});
+			firstEventTime.current.set(folderKey, Date.now());
+		}
+
+		const elapsed = Date.now() - (firstEventTime.current.get(folderKey) ?? Date.now());
+		if (elapsed >= MAX_WAIT_MS) {
+			const existingTimeout = debounceTimers.current.get(folderKey);
+			if (existingTimeout) clearTimeout(existingTimeout);
+			flushFolder(folderKey);
+			return;
 		}
 
 		const existingTimeout = debounceTimers.current.get(folderKey);
 		if (existingTimeout) clearTimeout(existingTimeout);
 
-		const timeout = setTimeout(() => {
-			debounceTimers.current.delete(folderKey);
-			const pending = pendingByFolder.current.get(folderKey);
-			if (!pending) return;
-			pendingByFolder.current.delete(folderKey);
-			queueRef.current.push(pending);
-			processQueue();
-		}, DEBOUNCE_MS);
-
+		const timeout = setTimeout(() => flushFolder(folderKey), DEBOUNCE_MS);
 		debounceTimers.current.set(folderKey, timeout);
 	}
 
@@ -126,6 +147,7 @@ export function useFolderSync() {
 			}
 			debounceTimers.current.clear();
 			pendingByFolder.current.clear();
+			firstEventTime.current.clear();
 		};
 	}, []);
 }

From 4ca0787ab7bb8365b36c785ecd41366af32a6874 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 10:42:21 +0530
Subject: [PATCH 44/70] feat: add version history functionality to document
 management, enabling users to view and manage document versions through UI
 updates and backend integration

---
 .../app/tasks/celery_tasks/document_tasks.py  |  12 +-
 .../components/documents/DocumentNode.tsx     |  22 ++
 .../components/documents/FolderTreeView.tsx   |   3 +
 .../components/documents/version-history.tsx  | 251 ++++++++++++------
 .../layout/ui/sidebar/DocumentsSidebar.tsx    |  11 +
 5 files changed, 214 insertions(+), 85 deletions(-)

diff --git a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
index 16ac50967..506f8118c 100644
--- a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
+++ b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
@@ -1321,6 +1321,7 @@ async def _index_local_folder_async(
         doc_name = folder_name
 
     notification = None
+    notification_id: int | None = None
     heartbeat_task = None
 
     async with get_celery_session_maker()() as session:
@@ -1334,9 +1335,10 @@ async def _index_local_folder_async(
                     search_space_id=search_space_id,
                 )
             )
-            _start_heartbeat(notification.id)
+            notification_id = notification.id
+            _start_heartbeat(notification_id)
             heartbeat_task = asyncio.create_task(
-                _run_heartbeat_loop(notification.id)
+                _run_heartbeat_loop(notification_id)
             )
         except Exception:
             logger.warning(
@@ -1374,6 +1376,7 @@ async def _index_local_folder_async(
 
             if notification:
                 try:
+                    await session.refresh(notification)
                     if err:
                         await NotificationService.document_processing.notify_processing_completed(
                             session=session,
@@ -1395,6 +1398,7 @@ async def _index_local_folder_async(
             logger.exception(f"Local folder indexing failed: {e}")
             if notification:
                 try:
+                    await session.refresh(notification)
                     await NotificationService.document_processing.notify_processing_completed(
                         session=session,
                         notification=notification,
@@ -1406,5 +1410,5 @@ async def _index_local_folder_async(
         finally:
             if heartbeat_task:
                 heartbeat_task.cancel()
-            if notification:
-                _stop_heartbeat(notification.id)
+            if notification_id is not None:
+                _stop_heartbeat(notification_id)
diff --git a/surfsense_web/components/documents/DocumentNode.tsx b/surfsense_web/components/documents/DocumentNode.tsx
index dc92109b1..31d1bc7ca 100644
--- a/surfsense_web/components/documents/DocumentNode.tsx
+++ b/surfsense_web/components/documents/DocumentNode.tsx
@@ -5,6 +5,7 @@ import {
 	Clock,
 	Download,
 	Eye,
+	History,
 	MoreHorizontal,
 	Move,
 	PenLine,
@@ -38,6 +39,7 @@ import { Spinner } from "@/components/ui/spinner";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import type { DocumentTypeEnum } from "@/contracts/types/document.types";
 import { cn } from "@/lib/utils";
+import { isVersionableType } from "./version-history";
 import { DND_TYPES } from "./FolderNode";
 
 const EDITABLE_DOCUMENT_TYPES = new Set(["FILE", "NOTE"]);
@@ -60,6 +62,7 @@ interface DocumentNodeProps {
 	onDelete: (doc: DocumentNodeDoc) => void;
 	onMove: (doc: DocumentNodeDoc) => void;
 	onExport?: (doc: DocumentNodeDoc, format: string) => void;
+	onVersionHistory?: (doc: DocumentNodeDoc) => void;
 	contextMenuOpen?: boolean;
 	onContextMenuOpenChange?: (open: boolean) => void;
 }
@@ -74,6 +77,7 @@ export const DocumentNode = React.memo(function DocumentNode({
 	onDelete,
 	onMove,
 	onExport,
+	onVersionHistory,
 	contextMenuOpen,
 	onContextMenuOpenChange,
 }: DocumentNodeProps) {
@@ -246,6 +250,15 @@ export const DocumentNode = React.memo(function DocumentNode({
 									</DropdownMenuSubContent>
 								</DropdownMenuSub>
 							)}
+							{onVersionHistory && isVersionableType(doc.document_type) && (
+								<DropdownMenuItem
+									disabled={isProcessing}
+									onClick={() => onVersionHistory(doc)}
+								>
+									<History className="mr-2 h-4 w-4" />
+									Versions
+								</DropdownMenuItem>
+							)}
 							<DropdownMenuItem
 								className="text-destructive focus:text-destructive"
 								disabled={isProcessing}
@@ -286,6 +299,15 @@ export const DocumentNode = React.memo(function DocumentNode({
 							</ContextMenuSubContent>
 						</ContextMenuSub>
 					)}
+					{onVersionHistory && isVersionableType(doc.document_type) && (
+						<ContextMenuItem
+							disabled={isProcessing}
+							onClick={() => onVersionHistory(doc)}
+						>
+							<History className="mr-2 h-4 w-4" />
+							Versions
+						</ContextMenuItem>
+					)}
 					<ContextMenuItem
 						className="text-destructive focus:text-destructive"
 						disabled={isProcessing}
diff --git a/surfsense_web/components/documents/FolderTreeView.tsx b/surfsense_web/components/documents/FolderTreeView.tsx
index 01af73edc..6f64d6258 100644
--- a/surfsense_web/components/documents/FolderTreeView.tsx
+++ b/surfsense_web/components/documents/FolderTreeView.tsx
@@ -32,6 +32,7 @@ interface FolderTreeViewProps {
 	onDeleteDocument: (doc: DocumentNodeDoc) => void;
 	onMoveDocument: (doc: DocumentNodeDoc) => void;
 	onExportDocument?: (doc: DocumentNodeDoc, format: string) => void;
+	onVersionHistory?: (doc: DocumentNodeDoc) => void;
 	activeTypes: DocumentTypeEnum[];
 	searchQuery?: string;
 	onDropIntoFolder?: (
@@ -73,6 +74,7 @@ export function FolderTreeView({
 	onDeleteDocument,
 	onMoveDocument,
 	onExportDocument,
+	onVersionHistory,
 	activeTypes,
 	searchQuery,
 	onDropIntoFolder,
@@ -267,6 +269,7 @@ export function FolderTreeView({
 					onDelete={onDeleteDocument}
 					onMove={onMoveDocument}
 					onExport={onExportDocument}
+					onVersionHistory={onVersionHistory}
 					contextMenuOpen={openContextMenuId === `doc-${d.id}`}
 					onContextMenuOpenChange={(open) => setOpenContextMenuId(open ? `doc-${d.id}` : null)}
 				/>
diff --git a/surfsense_web/components/documents/version-history.tsx b/surfsense_web/components/documents/version-history.tsx
index 29740e079..f438a7190 100644
--- a/surfsense_web/components/documents/version-history.tsx
+++ b/surfsense_web/components/documents/version-history.tsx
@@ -1,16 +1,17 @@
 "use client";
 
 import { useCallback, useEffect, useState } from "react";
-import { Clock, RotateCcw } from "lucide-react";
+import { Check, ChevronRight, Clock, Copy, RotateCcw } from "lucide-react";
 import { Button } from "@/components/ui/button";
 import {
-	Sheet,
-	SheetContent,
-	SheetHeader,
-	SheetTitle,
-	SheetTrigger,
-} from "@/components/ui/sheet";
+	Dialog,
+	DialogContent,
+	DialogTitle,
+	DialogTrigger,
+} from "@/components/ui/dialog";
+import { Separator } from "@/components/ui/separator";
 import { Spinner } from "@/components/ui/spinner";
+import { cn } from "@/lib/utils";
 import { documentsApiService } from "@/lib/apis/documents-api.service";
 import { toast } from "sonner";
 
@@ -26,28 +27,72 @@ interface VersionHistoryProps {
 	documentType: string;
 }
 
+const VERSION_DOCUMENT_TYPES = new Set(["LOCAL_FOLDER_FILE", "OBSIDIAN_CONNECTOR"]);
+
+export function isVersionableType(documentType: string) {
+	return VERSION_DOCUMENT_TYPES.has(documentType);
+}
+
+const DIALOG_CLASSES =
+	"select-none max-w-[900px] w-[95vw] md:w-[90vw] h-[90vh] md:h-[80vh] max-h-[640px] flex flex-col md:flex-row p-0 gap-0 overflow-hidden [--card:var(--background)] dark:[--card:oklch(0.205_0_0)] dark:[--background:oklch(0.205_0_0)]";
+
 export function VersionHistoryButton({ documentId, documentType }: VersionHistoryProps) {
-	const showVersionHistory = documentType === "LOCAL_FOLDER_FILE" || documentType === "OBSIDIAN_CONNECTOR";
-	if (!showVersionHistory) return null;
+	if (!isVersionableType(documentType)) return null;
 
 	return (
-		<Sheet>
-			<SheetTrigger asChild>
+		<Dialog>
+			<DialogTrigger asChild>
 				<Button variant="ghost" size="sm" className="gap-1.5 text-xs">
 					<Clock className="h-3.5 w-3.5" />
 					Versions
 				</Button>
-			</SheetTrigger>
-			<SheetContent className="w-[400px] sm:w-[540px]">
-				<SheetHeader>
-					<SheetTitle>Version History</SheetTitle>
-				</SheetHeader>
+			</DialogTrigger>
+			<DialogContent className={DIALOG_CLASSES}>
+				<DialogTitle className="sr-only">Version History</DialogTitle>
 				<VersionHistoryPanel documentId={documentId} />
-			</SheetContent>
-		</Sheet>
+			</DialogContent>
+		</Dialog>
 	);
 }
 
+export function VersionHistoryDialog({
+	open,
+	onOpenChange,
+	documentId,
+}: {
+	open: boolean;
+	onOpenChange: (open: boolean) => void;
+	documentId: number;
+}) {
+	return (
+		<Dialog open={open} onOpenChange={onOpenChange}>
+			<DialogContent className={DIALOG_CLASSES}>
+				<DialogTitle className="sr-only">Version History</DialogTitle>
+				{open && <VersionHistoryPanel documentId={documentId} />}
+			</DialogContent>
+		</Dialog>
+	);
+}
+
+function formatRelativeTime(dateStr: string): string {
+	const now = Date.now();
+	const then = new Date(dateStr).getTime();
+	const diffMs = now - then;
+	const diffMin = Math.floor(diffMs / 60_000);
+	if (diffMin < 1) return "Just now";
+	if (diffMin < 60) return `${diffMin} minute${diffMin !== 1 ? "s" : ""} ago`;
+	const diffHr = Math.floor(diffMin / 60);
+	if (diffHr < 24) return `${diffHr} hour${diffHr !== 1 ? "s" : ""} ago`;
+	return new Date(dateStr).toLocaleDateString(undefined, {
+		weekday: "short",
+		month: "short",
+		day: "numeric",
+		year: "numeric",
+		hour: "numeric",
+		minute: "2-digit",
+	});
+}
+
 function VersionHistoryPanel({ documentId }: { documentId: number }) {
 	const [versions, setVersions] = useState<DocumentVersionSummary[]>([]);
 	const [loading, setLoading] = useState(true);
@@ -55,6 +100,7 @@ function VersionHistoryPanel({ documentId }: { documentId: number }) {
 	const [versionContent, setVersionContent] = useState<string>("");
 	const [contentLoading, setContentLoading] = useState(false);
 	const [restoring, setRestoring] = useState(false);
+	const [copied, setCopied] = useState(false);
 
 	const loadVersions = useCallback(async () => {
 		setLoading(true);
@@ -73,6 +119,7 @@ function VersionHistoryPanel({ documentId }: { documentId: number }) {
 	}, [loadVersions]);
 
 	const handleSelectVersion = async (versionNumber: number) => {
+		if (selectedVersion === versionNumber) return;
 		setSelectedVersion(versionNumber);
 		setContentLoading(true);
 		try {
@@ -101,9 +148,15 @@ function VersionHistoryPanel({ documentId }: { documentId: number }) {
 		}
 	};
 
+	const handleCopy = () => {
+		navigator.clipboard.writeText(versionContent);
+		setCopied(true);
+		setTimeout(() => setCopied(false), 2000);
+	};
+
 	if (loading) {
 		return (
-			<div className="flex items-center justify-center py-12">
+			<div className="flex flex-1 items-center justify-center">
 				<Spinner size="lg" className="text-muted-foreground" />
 			</div>
 		);
@@ -111,75 +164,111 @@ function VersionHistoryPanel({ documentId }: { documentId: number }) {
 
 	if (versions.length === 0) {
 		return (
-			<div className="flex flex-col items-center justify-center py-12 text-muted-foreground">
-				<Clock className="h-8 w-8 mb-2 opacity-50" />
+			<div className="flex flex-1 flex-col items-center justify-center text-muted-foreground">
 				<p className="text-sm">No version history available yet.</p>
 				<p className="text-xs mt-1">Versions are created when file content changes.</p>
 			</div>
 		);
 	}
 
-	return (
-		<div className="flex flex-col gap-4 pt-4 h-full">
-			<div className="flex-1 overflow-y-auto space-y-2">
-				{versions.map((v) => (
-					<div
-						key={v.version_number}
-						className={`rounded-lg border p-3 cursor-pointer transition-colors ${
-							selectedVersion === v.version_number
-								? "border-primary bg-primary/5"
-								: "border-border hover:border-primary/50"
-						}`}
-						onClick={() => handleSelectVersion(v.version_number)}
-					>
-						<div className="flex items-center justify-between">
-							<div className="space-y-1">
-								<p className="text-sm font-medium">Version {v.version_number}</p>
-								{v.created_at && (
-									<p className="text-xs text-muted-foreground">
-										{new Date(v.created_at).toLocaleString()}
-									</p>
-								)}
-								{v.title && (
-									<p className="text-xs text-muted-foreground truncate max-w-[200px]">
-										{v.title}
-									</p>
-								)}
-							</div>
-							<Button
-								variant="outline"
-								size="sm"
-								className="shrink-0 gap-1"
-								disabled={restoring}
-								onClick={(e) => {
-									e.stopPropagation();
-									handleRestore(v.version_number);
-								}}
-							>
-								<RotateCcw className="h-3 w-3" />
-								Restore
-							</Button>
-						</div>
-					</div>
-				))}
-			</div>
+	const selectedVersionData = versions.find((v) => v.version_number === selectedVersion);
 
-			{selectedVersion !== null && (
-				<div className="border-t pt-4 max-h-[40vh] overflow-y-auto">
-					<h4 className="text-sm font-medium mb-2">
-						Preview — Version {selectedVersion}
-					</h4>
-					{contentLoading ? (
-						<div className="flex items-center justify-center py-6">
-							<Spinner size="sm" />
-						</div>
-					) : (
-						<pre className="text-xs whitespace-pre-wrap font-mono bg-muted/50 rounded-lg p-3 max-h-[30vh] overflow-y-auto">
-							{versionContent || "(empty)"}
-						</pre>
-					)}
+	return (
+		<>
+			{/* Left panel — version list */}
+			<nav className="w-full md:w-[260px] shrink-0 flex flex-col border-b md:border-b-0 md:border-r border-border">
+				<div className="px-4 pr-12 md:pr-4 pt-5 pb-2">
+					<h2 className="text-sm font-semibold text-foreground">Version History</h2>
 				</div>
-			)}
-		</div>
+				<div className="flex-1 overflow-y-auto p-2">
+					<div className="flex flex-col gap-0.5">
+						{versions.map((v) => (
+							<button
+								key={v.version_number}
+								type="button"
+								onClick={() => handleSelectVersion(v.version_number)}
+								className={cn(
+									"flex items-center gap-2 rounded-lg px-3 py-2.5 text-left transition-colors focus:outline-none focus-visible:outline-none w-full",
+									selectedVersion === v.version_number
+										? "bg-accent text-accent-foreground"
+										: "text-muted-foreground hover:bg-accent/50 hover:text-foreground"
+								)}
+							>
+								<div className="flex-1 min-w-0 space-y-0.5">
+									<p className="text-sm font-medium truncate">
+										{v.created_at ? formatRelativeTime(v.created_at) : `Version ${v.version_number}`}
+									</p>
+									{v.title && (
+										<p className="text-xs text-muted-foreground truncate">
+											{v.title}
+										</p>
+									)}
+								</div>
+								<ChevronRight className="h-3.5 w-3.5 shrink-0 opacity-50" />
+							</button>
+						))}
+					</div>
+				</div>
+			</nav>
+
+			{/* Right panel — content preview */}
+			<div className="flex flex-1 flex-col overflow-hidden min-w-0">
+				{selectedVersion !== null && selectedVersionData ? (
+					<>
+						<div className="flex items-center justify-between pl-6 pr-14 pt-5 pb-2">
+							<h2 className="text-sm font-semibold truncate">
+								{selectedVersionData.title || `Version ${selectedVersion}`}
+							</h2>
+							<div className="flex items-center gap-1.5 shrink-0">
+								<Button
+									variant="outline"
+									size="sm"
+									className="gap-1.5 text-xs"
+									onClick={handleCopy}
+									disabled={contentLoading || copied}
+								>
+									{copied ? (
+										<Check className="h-3 w-3" />
+									) : (
+										<Copy className="h-3 w-3" />
+									)}
+									{copied ? "Copied" : "Copy"}
+								</Button>
+								<Button
+									variant="outline"
+									size="sm"
+									className="gap-1.5 text-xs"
+									disabled={restoring || contentLoading}
+									onClick={() => handleRestore(selectedVersion)}
+								>
+									{restoring ? (
+										<Spinner size="xs" />
+									) : (
+										<RotateCcw className="h-3 w-3" />
+									)}
+									Restore
+								</Button>
+							</div>
+						</div>
+						<Separator />
+						<div className="flex-1 overflow-y-auto px-6 py-4">
+							{contentLoading ? (
+								<div className="flex items-center justify-center py-12">
+									<Spinner size="sm" className="text-muted-foreground" />
+								</div>
+							) : (
+								<pre className="text-sm whitespace-pre-wrap font-mono leading-relaxed text-foreground/90">
+									{versionContent || "(empty)"}
+								</pre>
+							)}
+						</div>
+					</>
+				) : (
+					<div className="flex flex-1 items-center justify-center text-muted-foreground">
+						<p className="text-sm">Select a version to preview</p>
+					</div>
+				)}
+			</div>
+		</>
 	);
 }
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index 7aa518361..031390c9e 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -21,6 +21,7 @@ import type { DocumentNodeDoc } from "@/components/documents/DocumentNode";
 import type { FolderDisplay } from "@/components/documents/FolderNode";
 import { FolderPickerDialog } from "@/components/documents/FolderPickerDialog";
 import { FolderTreeView } from "@/components/documents/FolderTreeView";
+import { VersionHistoryDialog } from "@/components/documents/version-history";
 import { JsonMetadataViewer } from "@/components/json-metadata-viewer";
 import { EXPORT_FILE_EXTENSIONS } from "@/components/shared/ExportMenuItems";
 import {
@@ -579,6 +580,7 @@ export function DocumentsSidebar({
 
 	const [bulkDeleteConfirmOpen, setBulkDeleteConfirmOpen] = useState(false);
 	const [isBulkDeleting, setIsBulkDeleting] = useState(false);
+	const [versionDocId, setVersionDocId] = useState<number | null>(null);
 
 	const handleBulkDeleteSelected = useCallback(async () => {
 		if (deletableSelectedIds.length === 0) return;
@@ -826,6 +828,7 @@ export function DocumentsSidebar({
 				onDeleteDocument={(doc) => handleDeleteDocument(doc.id)}
 				onMoveDocument={handleMoveDocument}
 				onExportDocument={handleExportDocument}
+				onVersionHistory={(doc) => setVersionDocId(doc.id)}
 				activeTypes={activeTypes}
 				onDropIntoFolder={handleDropIntoFolder}
 				onReorderFolder={handleReorderFolder}
@@ -850,6 +853,14 @@ export function DocumentsSidebar({
 			}}
 		/>
 
+		{versionDocId !== null && (
+			<VersionHistoryDialog
+				open
+				onOpenChange={(open) => { if (!open) setVersionDocId(null); }}
+				documentId={versionDocId}
+			/>
+		)}
+
 		<FolderPickerDialog
 				open={folderPickerOpen}
 				onOpenChange={setFolderPickerOpen}

From ca250910c09a2d9aaa3c553aba350b749a7ecdc5 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 10:56:43 +0530
Subject: [PATCH 45/70] fix: update version history messages for clarity by
 removing unnecessary punctuation

---
 surfsense_web/components/documents/version-history.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/surfsense_web/components/documents/version-history.tsx b/surfsense_web/components/documents/version-history.tsx
index f438a7190..7aba92b47 100644
--- a/surfsense_web/components/documents/version-history.tsx
+++ b/surfsense_web/components/documents/version-history.tsx
@@ -165,8 +165,8 @@ function VersionHistoryPanel({ documentId }: { documentId: number }) {
 	if (versions.length === 0) {
 		return (
 			<div className="flex flex-1 flex-col items-center justify-center text-muted-foreground">
-				<p className="text-sm">No version history available yet.</p>
-				<p className="text-xs mt-1">Versions are created when file content changes.</p>
+				<p className="text-sm">No version history available yet</p>
+				<p className="text-xs mt-1">Versions are created when file content changes</p>
 			</div>
 		);
 	}

From 79f19b9bc637d13bf89a8c08ae2e815123093491 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 11:10:46 +0530
Subject: [PATCH 46/70] fix: adjust layout in DocumentsSidebar for improved UI
 responsiveness and interaction, including changes to button styles and
 positioning

---
 .../components/layout/ui/sidebar/DocumentsSidebar.tsx     | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index 031390c9e..24f6666c9 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -784,12 +784,13 @@ export function DocumentsSidebar({
 			/>
 				</div>
 
+			<div className="relative flex-1 min-h-0 overflow-auto">
 				{deletableSelectedIds.length > 0 && (
-					<div className="shrink-0 flex items-center justify-center px-4 py-1.5 animate-in fade-in duration-150">
+					<div className="absolute inset-x-0 top-0 z-10 flex items-center justify-center px-4 py-1.5 animate-in fade-in duration-150 pointer-events-none">
 						<button
 							type="button"
 							onClick={() => setBulkDeleteConfirmOpen(true)}
-							className="flex items-center gap-1.5 px-3 py-1 rounded-md bg-destructive text-destructive-foreground shadow-sm text-xs font-medium hover:bg-destructive/90 transition-colors"
+							className="pointer-events-auto flex items-center gap-1.5 px-3 py-1 rounded-md bg-destructive text-destructive-foreground shadow-lg text-xs font-medium hover:bg-destructive/90 transition-colors"
 						>
 							<Trash2 size={12} />
 							Delete {deletableSelectedIds.length}{" "}
@@ -798,7 +799,7 @@ export function DocumentsSidebar({
 					</div>
 				)}
 
-				<FolderTreeView
+			<FolderTreeView
 				folders={treeFolders}
 				documents={searchFilteredDocuments}
 				expandedIds={expandedIds}
@@ -837,6 +838,7 @@ export function DocumentsSidebar({
 			onStopWatchingFolder={handleStopWatching}
 			onViewFolderMetadata={handleViewFolderMetadata}
 		/>
+			</div>
 		</div>
 
 		<JsonMetadataViewer

From 525fae5abf3796cfe5bc5ecd3b39c207878a7894 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 11:19:54 +0530
Subject: [PATCH 47/70] feat: trigger document reindexing after restoring a
 document version to ensure content is up-to-date

---
 surfsense_backend/app/routes/documents_routes.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index e6eed7836..083ed2b89 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -1285,6 +1285,9 @@ async def restore_document_version(
     document.content_needs_reindexing = True
     await session.commit()
 
+    from app.tasks.celery_tasks.document_reindex_tasks import reindex_document_task
+    reindex_document_task.delay(document_id, str(user.id))
+
     return {
         "message": f"Restored version {version_number}",
         "document_id": document_id,

From 3833084dad3444d7bf534a7b39dc62ebf24a89fd Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 11:45:53 +0530
Subject: [PATCH 48/70] feat: changed the revision number of folder alembic
 migration

---
 ...ing.py => 118_add_local_folder_sync_and_versioning.py} | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
 rename surfsense_backend/alembic/versions/{117_add_local_folder_sync_and_versioning.py => 118_add_local_folder_sync_and_versioning.py} (98%)

diff --git a/surfsense_backend/alembic/versions/117_add_local_folder_sync_and_versioning.py b/surfsense_backend/alembic/versions/118_add_local_folder_sync_and_versioning.py
similarity index 98%
rename from surfsense_backend/alembic/versions/117_add_local_folder_sync_and_versioning.py
rename to surfsense_backend/alembic/versions/118_add_local_folder_sync_and_versioning.py
index e322a608d..1fef9fbcb 100644
--- a/surfsense_backend/alembic/versions/117_add_local_folder_sync_and_versioning.py
+++ b/surfsense_backend/alembic/versions/118_add_local_folder_sync_and_versioning.py
@@ -1,7 +1,7 @@
 """Add LOCAL_FOLDER_FILE document type, folder metadata, and document_versions table
 
-Revision ID: 117
-Revises: 116
+Revision ID: 118
+Revises: 117
 """
 
 from collections.abc import Sequence
@@ -10,8 +10,8 @@ import sqlalchemy as sa
 
 from alembic import op
 
-revision: str = "117"
-down_revision: str | None = "116"
+revision: str = "118"
+down_revision: str | None = "117"
 branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
 

From 3621951f2aeceebaff70328ffe8a6c91e9bad83d Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Thu, 2 Apr 2026 23:21:57 -0700
Subject: [PATCH 49/70] perf: throttle scroll handlers with
 requestAnimationFrame

Wrap scroll handlers in thread.tsx, InboxSidebar.tsx, and
DocumentsTableShell.tsx with requestAnimationFrame batching so scroll
position state updates fire at most once per animation frame instead of
on every scroll event (up to 60/sec at 60fps). Add cleanup useEffect to
cancel pending frames on unmount.

Fixes #1103
---
 .../(manage)/components/DocumentsTableShell.tsx      | 12 +++++++++---
 surfsense_web/components/assistant-ui/thread.tsx     | 12 +++++++++---
 .../components/layout/ui/sidebar/InboxSidebar.tsx    | 12 +++++++++---
 3 files changed, 27 insertions(+), 9 deletions(-)

diff --git a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx
index ceef9f2e1..dc8966571 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx
@@ -267,12 +267,18 @@ export function DocumentsTableShell({
 	const [metadataJson, setMetadataJson] = useState<Record<string, unknown> | null>(null);
 	const [metadataLoading, setMetadataLoading] = useState(false);
 	const [previewScrollPos, setPreviewScrollPos] = useState<"top" | "middle" | "bottom">("top");
+	const previewRafRef = useRef<number>();
 	const handlePreviewScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
 		const el = e.currentTarget;
-		const atTop = el.scrollTop <= 2;
-		const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= 2;
-		setPreviewScrollPos(atTop ? "top" : atBottom ? "bottom" : "middle");
+		if (previewRafRef.current) return;
+		previewRafRef.current = requestAnimationFrame(() => {
+			const atTop = el.scrollTop <= 2;
+			const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= 2;
+			setPreviewScrollPos(atTop ? "top" : atBottom ? "bottom" : "middle");
+			previewRafRef.current = undefined;
+		});
 	}, []);
+	useEffect(() => () => { if (previewRafRef.current) cancelAnimationFrame(previewRafRef.current); }, []);
 
 	const [deleteDoc, setDeleteDoc] = useState<Document | null>(null);
 	const [isDeleting, setIsDeleting] = useState(false);
diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 0d0163d8a..0f230cec3 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -816,12 +816,18 @@ const ComposerAction: FC<ComposerActionProps> = ({ isBlockedByOtherUser = false
 	const isDesktop = useMediaQuery("(min-width: 640px)");
 	const { openDialog: openUploadDialog } = useDocumentUploadDialog();
 	const [toolsScrollPos, setToolsScrollPos] = useState<"top" | "middle" | "bottom">("top");
+	const toolsRafRef = useRef<number>();
 	const handleToolsScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
 		const el = e.currentTarget;
-		const atTop = el.scrollTop <= 2;
-		const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= 2;
-		setToolsScrollPos(atTop ? "top" : atBottom ? "bottom" : "middle");
+		if (toolsRafRef.current) return;
+		toolsRafRef.current = requestAnimationFrame(() => {
+			const atTop = el.scrollTop <= 2;
+			const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= 2;
+			setToolsScrollPos(atTop ? "top" : atBottom ? "bottom" : "middle");
+			toolsRafRef.current = undefined;
+		});
 	}, []);
+	useEffect(() => () => { if (toolsRafRef.current) cancelAnimationFrame(toolsRafRef.current); }, []);
 	const isComposerTextEmpty = useAuiState(({ composer }) => {
 		const text = composer.text?.trim() || "";
 		return text.length === 0;
diff --git a/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx
index 72400a589..4aa8d4c60 100644
--- a/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx
@@ -178,12 +178,18 @@ export function InboxSidebarContent({
 	const [mounted, setMounted] = useState(false);
 	const [openDropdown, setOpenDropdown] = useState<"filter" | null>(null);
 	const [connectorScrollPos, setConnectorScrollPos] = useState<"top" | "middle" | "bottom">("top");
+	const connectorRafRef = useRef<number>();
 	const handleConnectorScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
 		const el = e.currentTarget;
-		const atTop = el.scrollTop <= 2;
-		const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= 2;
-		setConnectorScrollPos(atTop ? "top" : atBottom ? "bottom" : "middle");
+		if (connectorRafRef.current) return;
+		connectorRafRef.current = requestAnimationFrame(() => {
+			const atTop = el.scrollTop <= 2;
+			const atBottom = el.scrollHeight - el.scrollTop - el.clientHeight <= 2;
+			setConnectorScrollPos(atTop ? "top" : atBottom ? "bottom" : "middle");
+			connectorRafRef.current = undefined;
+		});
 	}, []);
+	useEffect(() => () => { if (connectorRafRef.current) cancelAnimationFrame(connectorRafRef.current); }, []);
 	const [filterDrawerOpen, setFilterDrawerOpen] = useState(false);
 	const [markingAsReadId, setMarkingAsReadId] = useState<number | null>(null);
 

From e38a0ff7c345cb83121f7983eec838cfdf579f66 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Thu, 2 Apr 2026 23:43:19 -0700
Subject: [PATCH 50/70] style: format useEffect cleanup to satisfy biome

---
 .../documents/(manage)/components/DocumentsTableShell.tsx  | 7 ++++++-
 surfsense_web/components/assistant-ui/thread.tsx           | 7 ++++++-
 .../components/layout/ui/sidebar/InboxSidebar.tsx          | 7 ++++++-
 3 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx
index dc8966571..748fb1911 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsTableShell.tsx
@@ -278,7 +278,12 @@ export function DocumentsTableShell({
 			previewRafRef.current = undefined;
 		});
 	}, []);
-	useEffect(() => () => { if (previewRafRef.current) cancelAnimationFrame(previewRafRef.current); }, []);
+	useEffect(
+		() => () => {
+			if (previewRafRef.current) cancelAnimationFrame(previewRafRef.current);
+		},
+		[]
+	);
 
 	const [deleteDoc, setDeleteDoc] = useState<Document | null>(null);
 	const [isDeleting, setIsDeleting] = useState(false);
diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 0f230cec3..718bf3961 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -827,7 +827,12 @@ const ComposerAction: FC<ComposerActionProps> = ({ isBlockedByOtherUser = false
 			toolsRafRef.current = undefined;
 		});
 	}, []);
-	useEffect(() => () => { if (toolsRafRef.current) cancelAnimationFrame(toolsRafRef.current); }, []);
+	useEffect(
+		() => () => {
+			if (toolsRafRef.current) cancelAnimationFrame(toolsRafRef.current);
+		},
+		[]
+	);
 	const isComposerTextEmpty = useAuiState(({ composer }) => {
 		const text = composer.text?.trim() || "";
 		return text.length === 0;
diff --git a/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx
index 4aa8d4c60..525b7cf74 100644
--- a/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/InboxSidebar.tsx
@@ -189,7 +189,12 @@ export function InboxSidebarContent({
 			connectorRafRef.current = undefined;
 		});
 	}, []);
-	useEffect(() => () => { if (connectorRafRef.current) cancelAnimationFrame(connectorRafRef.current); }, []);
+	useEffect(
+		() => () => {
+			if (connectorRafRef.current) cancelAnimationFrame(connectorRafRef.current);
+		},
+		[]
+	);
 	const [filterDrawerOpen, setFilterDrawerOpen] = useState(false);
 	const [markingAsReadId, setMarkingAsReadId] = useState<number | null>(null);
 

From b9b2bac16f89203e16b637ab12e3edb5ef3b4589 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Thu, 2 Apr 2026 23:59:15 -0700
Subject: [PATCH 51/70] fix: clean up onboarding tour timer leaks

Fix two timer cleanup bugs in onboarding-tour.tsx:

1. Remove cleanup return from useCallback (only works in useEffect).
   Clear retryTimerRef at the start of updateTarget and in a
   dedicated useEffect cleanup instead.

2. Track recursive setTimeout calls via startCheckTimerRef so they
   are properly cancelled on unmount instead of leaking.

Fixes #1091
---
 surfsense_web/components/onboarding-tour.tsx | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/surfsense_web/components/onboarding-tour.tsx b/surfsense_web/components/onboarding-tour.tsx
index 1c52169cb..d762d9c15 100644
--- a/surfsense_web/components/onboarding-tour.tsx
+++ b/surfsense_web/components/onboarding-tour.tsx
@@ -429,6 +429,7 @@ export function OnboardingTour() {
 	const pathname = usePathname();
 	const retryCountRef = useRef(0);
 	const retryTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const startCheckTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
 	const maxRetries = 10;
 	// Track previous user ID to detect user changes
 	const previousUserIdRef = useRef<string | null>(null);
@@ -460,6 +461,7 @@ export function OnboardingTour() {
 
 	// Find and track target element with retry logic
 	const updateTarget = useCallback(() => {
+		if (retryTimerRef.current) clearTimeout(retryTimerRef.current);
 		if (!currentStep) return;
 
 		const el = document.querySelector(currentStep.target);
@@ -480,11 +482,13 @@ export function OnboardingTour() {
 				}
 			}, 200);
 		}
+	}, [currentStep]);
 
+	useEffect(() => {
 		return () => {
 			if (retryTimerRef.current) clearTimeout(retryTimerRef.current);
 		};
-	}, [currentStep]);
+	}, []);
 
 	// Check if tour should run: localStorage + data validation with user ID tracking
 	useEffect(() => {
@@ -573,15 +577,15 @@ export function OnboardingTour() {
 				setPosition(calculatePosition(connectorEl, TOUR_STEPS[0].placement));
 			} else {
 				// Retry after delay
-				setTimeout(checkAndStartTour, 200);
+				startCheckTimerRef.current = setTimeout(checkAndStartTour, 200);
 			}
 		};
 
 		// Start checking after initial delay
-		const timer = setTimeout(checkAndStartTour, 500);
+		startCheckTimerRef.current = setTimeout(checkAndStartTour, 500);
 		return () => {
 			cancelled = true;
-			clearTimeout(timer);
+			if (startCheckTimerRef.current) clearTimeout(startCheckTimerRef.current);
 		};
 	}, [mounted, user?.id, searchSpaceId, pathname, threadsData, documentTypeCounts, connectors]);
 

From 388811194e720a28dce7a92e47757d01f9f2820f Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 12:33:47 +0530
Subject: [PATCH 52/70] feat: update DocumentUploadTab to use a dropdown for
 file and folder selection, enhancing user experience; also update upload
 limits and file size messages in multiple languages

---
 .../components/sources/DocumentUploadTab.tsx  | 73 ++++++-------------
 surfsense_web/messages/en.json                | 15 +++-
 surfsense_web/messages/es.json                | 15 +++-
 surfsense_web/messages/hi.json                | 15 +++-
 surfsense_web/messages/pt.json                | 15 +++-
 surfsense_web/messages/zh.json                | 17 +++--
 6 files changed, 80 insertions(+), 70 deletions(-)

diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index f3b9166dc..9733bd2e6 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -413,18 +413,24 @@ export function DocumentUploadTab({
 		}
 
 		return (
-			<Button
-				variant="secondary"
-				size="sm"
-				className={`text-xs ${sizeClass} ${widthClass}`}
-				onClick={(e) => {
-					e.stopPropagation();
-					e.preventDefault();
-					fileInputRef.current?.click();
-				}}
-			>
-				{t("browse_files")}
-			</Button>
+			<DropdownMenu>
+				<DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
+					<Button variant="secondary" size="sm" className={`text-xs gap-1 ${sizeClass} ${widthClass}`}>
+						Browse
+						<ChevronDown className="h-3 w-3 opacity-60" />
+					</Button>
+				</DropdownMenuTrigger>
+				<DropdownMenuContent align="center" onClick={(e) => e.stopPropagation()}>
+					<DropdownMenuItem onClick={() => fileInputRef.current?.click()}>
+						<FileIcon className="h-4 w-4 mr-2" />
+						{t("browse_files")}
+					</DropdownMenuItem>
+					<DropdownMenuItem onClick={() => folderInputRef.current?.click()}>
+						<FolderOpen className="h-4 w-4 mr-2" />
+						{t("browse_folder")}
+					</DropdownMenuItem>
+				</DropdownMenuContent>
+			</DropdownMenu>
 		);
 	};
 
@@ -476,7 +482,7 @@ export function DocumentUploadTab({
 						<Upload className="h-10 w-10 text-muted-foreground" />
 						<div className="text-center space-y-1.5">
 							<p className="text-base font-medium">
-								{isElectron ? "Select files or folder" : "Tap to select files"}
+								{isElectron ? "Select files or folder" : "Tap to select files or folder"}
 							</p>
 							<p className="text-sm text-muted-foreground inline-flex items-center flex-wrap justify-center">
 								<span>{t("file_size_limit")}</span>
@@ -484,40 +490,9 @@ export function DocumentUploadTab({
 								<span>{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}</span>
 							</p>
 						</div>
-						{isElectron && (
-							<div className="w-full mt-1" onClick={(e) => e.stopPropagation()}>
-								{renderBrowseButton({ fullWidth: true })}
-							</div>
-						)}
-						{!isElectron && (
-							<div className="mt-2 flex gap-2">
-								<Button
-									variant="secondary"
-									size="sm"
-									className="text-xs"
-									onClick={(e) => {
-										e.stopPropagation();
-										e.preventDefault();
-										fileInputRef.current?.click();
-									}}
-								>
-									{t("browse_files")}
-								</Button>
-								<Button
-									variant="outline"
-									size="sm"
-									className="text-xs"
-									onClick={(e) => {
-										e.stopPropagation();
-										e.preventDefault();
-										folderInputRef.current?.click();
-									}}
-								>
-									<FolderOpen className="h-4 w-4 mr-1.5" />
-									{t("browse_folder")}
-								</Button>
-							</div>
-						)}
+						<div className="w-full mt-1" onClick={(e) => e.stopPropagation()}>
+							{renderBrowseButton({ fullWidth: true })}
+						</div>
 					</div>
 				)}
 			</div>
@@ -570,8 +545,8 @@ export function DocumentUploadTab({
 				)}
 			</div>
 
-			{/* FOLDER SELECTED */}
-			{selectedFolder && (
+			{/* FOLDER SELECTED (Electron only — web flattens folder contents into file list) */}
+			{isElectron && selectedFolder && (
 				<div className="rounded-lg border border-border p-3 space-y-2">
 					<div className="flex items-center gap-2">
 						<FolderOpen className="h-4 w-4 text-primary shrink-0" />
diff --git a/surfsense_web/messages/en.json b/surfsense_web/messages/en.json
index 47d08e921..3a8c0c632 100644
--- a/surfsense_web/messages/en.json
+++ b/surfsense_web/messages/en.json
@@ -376,11 +376,11 @@
 	"upload_documents": {
 		"title": "Upload Documents",
 		"subtitle": "Upload your files to make them searchable and accessible through AI-powered conversations.",
-		"file_size_limit": "Maximum file size: {maxMB}MB per file",
-		"upload_limits": "Upload files or entire folders",
+		"file_size_limit": "Maximum file size: 50MB per file",
+		"upload_limits": "Upload limit: {maxFiles} files, {maxSizeMB}MB total",
 		"drop_files": "Drop files or folders here",
 		"drag_drop": "Drag & drop files or folders here",
-		"or_browse": "or click to browse files and folders",
+		"or_browse": "or click to browse",
 		"browse_files": "Browse Files",
 		"browse_folder": "Browse Folder",
 		"selected_files": "Selected Files ({count})",
@@ -397,7 +397,14 @@
 		"file_types_desc": "These file types are supported based on your current ETL service configuration.",
 		"file_too_large": "File Too Large",
 		"file_too_large_desc": "\"{name}\" exceeds the {maxMB}MB per-file limit.",
-		"no_supported_files_in_folder": "No supported file types found in the selected folder."
+		"no_supported_files_in_folder": "No supported file types found in the selected folder.",
+		"remaining_capacity": "{files} files, {sizeMB}MB remaining",
+		"file_limit_reached": "File limit reached",
+		"file_limit_reached_desc": "Maximum of {max} files allowed",
+		"max_files_exceeded": "Too many files",
+		"max_files_exceeded_desc": "You can upload a maximum of {max} files at once",
+		"max_size_exceeded": "Total size exceeded",
+		"max_size_exceeded_desc": "Total upload size cannot exceed {max}MB"
 	},
 	"add_webpage": {
 		"title": "Add Webpages for Crawling",
diff --git a/surfsense_web/messages/es.json b/surfsense_web/messages/es.json
index e7761ba25..2de30d29d 100644
--- a/surfsense_web/messages/es.json
+++ b/surfsense_web/messages/es.json
@@ -376,11 +376,11 @@
 	"upload_documents": {
 		"title": "Subir documentos",
 		"subtitle": "Sube tus archivos para hacerlos buscables y accesibles a través de conversaciones con IA.",
-		"file_size_limit": "Tamaño máximo de archivo: {maxMB} MB por archivo",
-		"upload_limits": "Sube archivos o carpetas enteras",
+		"file_size_limit": "Tamaño máximo de archivo: 50 MB por archivo",
+		"upload_limits": "Límite de subida: {maxFiles} archivos, {maxSizeMB} MB en total",
 		"drop_files": "Suelta archivos o carpetas aquí",
 		"drag_drop": "Arrastra y suelta archivos o carpetas aquí",
-		"or_browse": "o haz clic para explorar archivos y carpetas",
+		"or_browse": "o haz clic para explorar",
 		"browse_files": "Explorar archivos",
 		"browse_folder": "Explorar carpeta",
 		"selected_files": "Archivos seleccionados ({count})",
@@ -397,7 +397,14 @@
 		"file_types_desc": "Estos tipos de archivo son soportados según la configuración actual de tu servicio ETL.",
 		"file_too_large": "Archivo demasiado grande",
 		"file_too_large_desc": "\"{name}\" excede el límite de {maxMB} MB por archivo.",
-		"no_supported_files_in_folder": "No se encontraron tipos de archivo compatibles en la carpeta seleccionada."
+		"no_supported_files_in_folder": "No se encontraron tipos de archivo compatibles en la carpeta seleccionada.",
+		"remaining_capacity": "{files} archivos, {sizeMB}MB restante",
+		"file_limit_reached": "Límite de archivos alcanzado",
+		"file_limit_reached_desc": "Máximo de {max} archivos permitidos",
+		"max_files_exceeded": "Demasiados archivos",
+		"max_files_exceeded_desc": "Puedes subir un máximo de {max} archivos a la vez",
+		"max_size_exceeded": "Tamaño total excedido",
+		"max_size_exceeded_desc": "El tamaño total de subida no puede exceder {max}MB"
 	},
 	"add_webpage": {
 		"title": "Agregar páginas web para rastreo",
diff --git a/surfsense_web/messages/hi.json b/surfsense_web/messages/hi.json
index 957533206..c27291e3b 100644
--- a/surfsense_web/messages/hi.json
+++ b/surfsense_web/messages/hi.json
@@ -376,11 +376,11 @@
 	"upload_documents": {
 		"title": "दस्तावेज़ अपलोड करें",
 		"subtitle": "AI-संचालित बातचीत के माध्यम से अपनी फ़ाइलों को खोजने योग्य और सुलभ बनाने के लिए अपलोड करें।",
-		"file_size_limit": "अधिकतम फ़ाइल आकार: प्रति फ़ाइल {maxMB}MB",
-		"upload_limits": "फ़ाइलें या पूरे फ़ोल्डर अपलोड करें",
+		"file_size_limit": "अधिकतम फ़ाइल आकार: प्रति फ़ाइल 50MB",
+		"upload_limits": "अपलोड सीमा: {maxFiles} फ़ाइलें, कुल {maxSizeMB}MB",
 		"drop_files": "फ़ाइलें या फ़ोल्डर यहां छोड़ें",
 		"drag_drop": "फ़ाइलें या फ़ोल्डर यहां खींचें और छोड़ें",
-		"or_browse": "या फ़ाइलें और फ़ोल्डर ब्राउज़ करने के लिए क्लिक करें",
+		"or_browse": "या ब्राउज़ करने के लिए क्लिक करें",
 		"browse_files": "फ़ाइलें ब्राउज़ करें",
 		"browse_folder": "फ़ोल्डर ब्राउज़ करें",
 		"selected_files": "चयनित फ़ाइलें ({count})",
@@ -397,7 +397,14 @@
 		"file_types_desc": "ये फ़ाइल प्रकार आपकी वर्तमान ETL सेवा कॉन्फ़िगरेशन के आधार पर समर्थित हैं।",
 		"file_too_large": "फ़ाइल बहुत बड़ी है",
 		"file_too_large_desc": "\"{name}\" प्रति फ़ाइल {maxMB}MB की सीमा से अधिक है।",
-		"no_supported_files_in_folder": "चयनित फ़ोल्डर में कोई समर्थित फ़ाइल प्रकार नहीं मिला।"
+		"no_supported_files_in_folder": "चयनित फ़ोल्डर में कोई समर्थित फ़ाइल प्रकार नहीं मिला।",
+		"remaining_capacity": "{files} फ़ाइलें, {sizeMB}MB शेष",
+		"file_limit_reached": "फ़ाइल सीमा पूरी हो गई",
+		"file_limit_reached_desc": "अधिकतम {max} फ़ाइलें अनुमत हैं",
+		"max_files_exceeded": "बहुत सारी फ़ाइलें",
+		"max_files_exceeded_desc": "आप एक बार में अधिकतम {max} फ़ाइलें अपलोड कर सकते हैं",
+		"max_size_exceeded": "कुल आकार सीमा पार",
+		"max_size_exceeded_desc": "कुल अपलोड आकार {max}MB से अधिक नहीं हो सकता"
 	},
 	"add_webpage": {
 		"title": "क्रॉलिंग के लिए वेबपेज जोड़ें",
diff --git a/surfsense_web/messages/pt.json b/surfsense_web/messages/pt.json
index 9aec7af48..eeb417a27 100644
--- a/surfsense_web/messages/pt.json
+++ b/surfsense_web/messages/pt.json
@@ -376,11 +376,11 @@
 	"upload_documents": {
 		"title": "Enviar documentos",
 		"subtitle": "Envie seus arquivos para torná-los pesquisáveis e acessíveis através de conversas com IA.",
-		"file_size_limit": "Tamanho máximo do arquivo: {maxMB} MB por arquivo",
-		"upload_limits": "Envie arquivos ou pastas inteiras",
+		"file_size_limit": "Tamanho máximo do arquivo: 50 MB por arquivo",
+		"upload_limits": "Limite de envio: {maxFiles} arquivos, {maxSizeMB} MB no total",
 		"drop_files": "Solte arquivos ou pastas aqui",
 		"drag_drop": "Arraste e solte arquivos ou pastas aqui",
-		"or_browse": "ou clique para navegar arquivos e pastas",
+		"or_browse": "ou clique para navegar",
 		"browse_files": "Navegar arquivos",
 		"browse_folder": "Navegar pasta",
 		"selected_files": "Arquivos selecionados ({count})",
@@ -397,7 +397,14 @@
 		"file_types_desc": "Estes tipos de arquivo são suportados com base na configuração atual do seu serviço ETL.",
 		"file_too_large": "Arquivo muito grande",
 		"file_too_large_desc": "\"{name}\" excede o limite de {maxMB} MB por arquivo.",
-		"no_supported_files_in_folder": "Nenhum tipo de arquivo suportado encontrado na pasta selecionada."
+		"no_supported_files_in_folder": "Nenhum tipo de arquivo suportado encontrado na pasta selecionada.",
+		"remaining_capacity": "{files} arquivos, {sizeMB}MB restante",
+		"file_limit_reached": "Limite de arquivos atingido",
+		"file_limit_reached_desc": "Máximo de {max} arquivos permitidos",
+		"max_files_exceeded": "Muitos arquivos",
+		"max_files_exceeded_desc": "Você pode enviar no máximo {max} arquivos de uma vez",
+		"max_size_exceeded": "Tamanho total excedido",
+		"max_size_exceeded_desc": "O tamanho total do envio não pode exceder {max}MB"
 	},
 	"add_webpage": {
 		"title": "Adicionar páginas web para rastreamento",
diff --git a/surfsense_web/messages/zh.json b/surfsense_web/messages/zh.json
index 3ceab2443..2ee18a346 100644
--- a/surfsense_web/messages/zh.json
+++ b/surfsense_web/messages/zh.json
@@ -360,11 +360,11 @@
 	"upload_documents": {
 		"title": "上传文档",
 		"subtitle": "上传您的文件，使其可通过 AI 对话进行搜索和访问。",
-		"file_size_limit": "最大文件大小：每个文件 {maxMB}MB",
-		"upload_limits": "上传文件或整个文件夹",
+		"file_size_limit": "最大文件大小：每个文件 50MB",
+		"upload_limits": "上传限制：最多 {maxFiles} 个文件，总大小不超过 {maxSizeMB}MB",
 		"drop_files": "将文件或文件夹拖放到此处",
-		"drag_drop": "将文件或文件夹拖放到此处",
-		"or_browse": "或点击浏览文件和文件夹",
+		"drag_drop": "拖放文件或文件夹到这里",
+		"or_browse": "或点击浏览",
 		"browse_files": "浏览文件",
 		"browse_folder": "浏览文件夹",
 		"selected_files": "已选择的文件 ({count})",
@@ -381,7 +381,14 @@
 		"file_types_desc": "根据您当前的 ETL 服务配置支持这些文件类型。",
 		"file_too_large": "文件过大",
 		"file_too_large_desc": "\"{name}\" 超过了每个文件 {maxMB}MB 的限制。",
-		"no_supported_files_in_folder": "所选文件夹中没有找到支持的文件类型。"
+		"no_supported_files_in_folder": "所选文件夹中没有找到支持的文件类型。",
+		"remaining_capacity": "剩余 {files} 个文件，{sizeMB}MB",
+		"file_limit_reached": "已达文件数量上限",
+		"file_limit_reached_desc": "最多允许 {max} 个文件",
+		"max_files_exceeded": "文件数量过多",
+		"max_files_exceeded_desc": "一次最多上传 {max} 个文件",
+		"max_size_exceeded": "总大小超出限制",
+		"max_size_exceeded_desc": "总上传大小不能超过 {max}MB"
 	},
 	"add_webpage": {
 		"title": "添加网页爬取",

From 134beec3920c9c2cc2c84e3588828b8294d856c9 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Fri, 3 Apr 2026 00:05:06 -0700
Subject: [PATCH 53/70] fix: clear upload progress interval on unmount

Store the progress setInterval ID in a ref and clear it in a
useEffect cleanup. Previously the interval was stored in a local
variable and only cleared in onSuccess/onError callbacks, leaking
if the component unmounted mid-upload.

Fixes #1090
---
 .../components/sources/DocumentUploadTab.tsx    | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index 723a3ad36..5c8ec83a5 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -4,7 +4,7 @@ import { useAtom } from "jotai";
 import { CheckCircle2, FileType, FolderOpen, Info, Upload, X } from "lucide-react";
 
 import { useTranslations } from "next-intl";
-import { type ChangeEvent, useCallback, useMemo, useRef, useState } from "react";
+import { type ChangeEvent, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useDropzone } from "react-dropzone";
 import { toast } from "sonner";
 import { uploadDocumentMutationAtom } from "@/atoms/documents/document-mutation.atoms";
@@ -132,6 +132,15 @@ export function DocumentUploadTab({
 	const { mutate: uploadDocuments, isPending: isUploading } = uploadDocumentMutation;
 	const fileInputRef = useRef<HTMLInputElement>(null);
 	const folderInputRef = useRef<HTMLInputElement>(null);
+	const progressIntervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+
+	useEffect(() => {
+		return () => {
+			if (progressIntervalRef.current) {
+				clearInterval(progressIntervalRef.current);
+			}
+		};
+	}, []);
 
 	const acceptedFileTypes = useMemo(() => {
 		const etlService = process.env.NEXT_PUBLIC_ETL_SERVICE;
@@ -236,7 +245,7 @@ export function DocumentUploadTab({
 		setUploadProgress(0);
 		trackDocumentUploadStarted(Number(searchSpaceId), files.length, totalFileSize);
 
-		const progressInterval = setInterval(() => {
+		progressIntervalRef.current = setInterval(() => {
 			setUploadProgress((prev) => (prev >= 90 ? prev : prev + Math.random() * 10));
 		}, 200);
 
@@ -249,14 +258,14 @@ export function DocumentUploadTab({
 			},
 			{
 				onSuccess: () => {
-					clearInterval(progressInterval);
+					if (progressIntervalRef.current) clearInterval(progressIntervalRef.current);
 					setUploadProgress(100);
 					trackDocumentUploadSuccess(Number(searchSpaceId), files.length);
 					toast(t("upload_initiated"), { description: t("upload_initiated_desc") });
 					onSuccess?.();
 				},
 				onError: (error: unknown) => {
-					clearInterval(progressInterval);
+					if (progressIntervalRef.current) clearInterval(progressIntervalRef.current);
 					setUploadProgress(0);
 					const message = error instanceof Error ? error.message : "Upload failed";
 					trackDocumentUploadFailure(Number(searchSpaceId), message);

From 8171605fae6737b4e95cc07d05fe5467493265dd Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 13:05:42 +0530
Subject: [PATCH 54/70] refactor: remove metadata viewing functionality from
 FolderNode, FolderTreeView, and DocumentsSidebar components

---
 .../components/documents/FolderNode.tsx       | 10 +-----
 .../components/documents/FolderTreeView.tsx   |  3 --
 .../layout/ui/sidebar/DocumentsSidebar.tsx    | 34 -------------------
 3 files changed, 1 insertion(+), 46 deletions(-)

diff --git a/surfsense_web/components/documents/FolderNode.tsx b/surfsense_web/components/documents/FolderNode.tsx
index 41c1d8f73..909f965f9 100644
--- a/surfsense_web/components/documents/FolderNode.tsx
+++ b/surfsense_web/components/documents/FolderNode.tsx
@@ -80,7 +80,6 @@ interface FolderNodeProps {
 	isWatched?: boolean;
 	onRescan?: (folder: FolderDisplay) => void;
 	onStopWatching?: (folder: FolderDisplay) => void;
-	onViewMetadata?: (folder: FolderDisplay) => void;
 }
 
 function getDropZone(
@@ -122,7 +121,6 @@ export const FolderNode = React.memo(function FolderNode({
 	isWatched,
 	onRescan,
 	onStopWatching,
-	onViewMetadata,
 }: FolderNodeProps) {
 	const [renameValue, setRenameValue] = useState(folder.name);
 	const inputRef = useRef<HTMLInputElement>(null);
@@ -258,13 +256,7 @@ export const FolderNode = React.memo(function FolderNode({
 						isOver && !canDrop && "cursor-not-allowed"
 					)}
 					style={{ paddingLeft: `${depth * 16 + 4}px` }}
-				onClick={(e) => {
-					if ((e.ctrlKey || e.metaKey) && onViewMetadata) {
-						e.preventDefault();
-						e.stopPropagation();
-						onViewMetadata(folder);
-						return;
-					}
+				onClick={() => {
 					onToggleExpand(folder.id);
 				}}
 				onKeyDown={(e) => {
diff --git a/surfsense_web/components/documents/FolderTreeView.tsx b/surfsense_web/components/documents/FolderTreeView.tsx
index 6f64d6258..3aa8ce9d8 100644
--- a/surfsense_web/components/documents/FolderTreeView.tsx
+++ b/surfsense_web/components/documents/FolderTreeView.tsx
@@ -44,7 +44,6 @@ interface FolderTreeViewProps {
 	watchedFolderIds?: Set<number>;
 	onRescanFolder?: (folder: FolderDisplay) => void;
 	onStopWatchingFolder?: (folder: FolderDisplay) => void;
-	onViewFolderMetadata?: (folder: FolderDisplay) => void;
 }
 
 function groupBy<T>(items: T[], keyFn: (item: T) => string | number): Record<string | number, T[]> {
@@ -82,7 +81,6 @@ export function FolderTreeView({
 	watchedFolderIds,
 	onRescanFolder,
 	onStopWatchingFolder,
-	onViewFolderMetadata,
 }: FolderTreeViewProps) {
 	const foldersByParent = useMemo(() => groupBy(folders, (f) => f.parentId ?? "root"), [folders]);
 
@@ -247,7 +245,6 @@ export function FolderTreeView({
 				isWatched={watchedFolderIds?.has(f.id)}
 				onRescan={onRescanFolder}
 				onStopWatching={onStopWatchingFolder}
-				onViewMetadata={onViewFolderMetadata}
 			/>
 			);
 
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index 24f6666c9..c10c5dc82 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -22,7 +22,6 @@ import type { FolderDisplay } from "@/components/documents/FolderNode";
 import { FolderPickerDialog } from "@/components/documents/FolderPickerDialog";
 import { FolderTreeView } from "@/components/documents/FolderTreeView";
 import { VersionHistoryDialog } from "@/components/documents/version-history";
-import { JsonMetadataViewer } from "@/components/json-metadata-viewer";
 import { EXPORT_FILE_EXTENSIONS } from "@/components/shared/ExportMenuItems";
 import {
 	AlertDialog,
@@ -97,10 +96,6 @@ export function DocumentsSidebar({
 	const [activeTypes, setActiveTypes] = useState<DocumentTypeEnum[]>([]);
 	const [watchedFolderIds, setWatchedFolderIds] = useState<Set<number>>(new Set());
 
-	const [metadataFolder, setMetadataFolder] = useState<FolderDisplay | null>(null);
-	const [metadataJson, setMetadataJson] = useState<Record<string, unknown> | null>(null);
-	const [metadataLoading, setMetadataLoading] = useState(false);
-
 	useEffect(() => {
 		const api = typeof window !== "undefined" ? window.electronAPI : null;
 		if (!api?.getWatchedFolders) return;
@@ -333,20 +328,6 @@ export function DocumentsSidebar({
 		[]
 	);
 
-	const handleViewFolderMetadata = useCallback(async (folder: FolderDisplay) => {
-		setMetadataFolder(folder);
-		setMetadataLoading(true);
-		try {
-			const fullFolder = await foldersApiService.getFolder(folder.id);
-			setMetadataJson((fullFolder.metadata as Record<string, unknown>) ?? {});
-		} catch (err) {
-			console.error("[DocumentsSidebar] Failed to fetch folder metadata:", err);
-			setMetadataJson({ error: "Failed to load folder metadata" });
-		} finally {
-			setMetadataLoading(false);
-		}
-	}, []);
-
 	const handleRenameFolder = useCallback(async (folder: FolderDisplay, newName: string) => {
 		try {
 			await foldersApiService.updateFolder(folder.id, { name: newName });
@@ -836,25 +817,10 @@ export function DocumentsSidebar({
 				watchedFolderIds={watchedFolderIds}
 				onRescanFolder={handleRescanFolder}
 			onStopWatchingFolder={handleStopWatching}
-			onViewFolderMetadata={handleViewFolderMetadata}
 		/>
 			</div>
 		</div>
 
-		<JsonMetadataViewer
-			title={metadataFolder?.name ?? "Folder"}
-			metadata={metadataJson}
-			loading={metadataLoading}
-			open={!!metadataFolder}
-			onOpenChange={(open) => {
-				if (!open) {
-					setMetadataFolder(null);
-					setMetadataJson(null);
-					setMetadataLoading(false);
-				}
-			}}
-		/>
-
 		{versionDocId !== null && (
 			<VersionHistoryDialog
 				open

From 6ace8850bb5ef433372f42c0129bafe92bdca6d6 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 13:10:25 +0530
Subject: [PATCH 55/70] fix: update button alignment in InlineCitation
 component for consistent styling

---
 surfsense_web/components/assistant-ui/inline-citation.tsx | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/inline-citation.tsx b/surfsense_web/components/assistant-ui/inline-citation.tsx
index 15ad11d94..42144f1d6 100644
--- a/surfsense_web/components/assistant-ui/inline-citation.tsx
+++ b/surfsense_web/components/assistant-ui/inline-citation.tsx
@@ -32,8 +32,7 @@ export const InlineCitation: FC<InlineCitationProps> = ({ chunkId, isDocsChunk =
 			<button
 				type="button"
 				onClick={() => setIsOpen(true)}
-				className="ml-0.5 inline-flex h-5 min-w-5 cursor-pointer items-center justify-center rounded-md bg-muted/60 px-1.5 text-[11px] font-medium text-muted-foreground align-super shadow-sm transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none"
-				title={`View source chunk #${chunkId}`}
+				className="ml-0.5 inline-flex h-5 min-w-5 cursor-pointer items-center justify-center rounded-md bg-muted/60 px-1.5 text-[11px] font-medium text-muted-foreground align-baseline shadow-sm transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none"				title={`View source chunk #${chunkId}`}
 			>
 				{chunkId}
 			</button>

From 746c730b2e03ae23a718d53023bf473fa673d3f7 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 13:14:40 +0530
Subject: [PATCH 56/70] chore: ran linting

---
 .../app/routes/documents_routes.py            |  63 ++---
 surfsense_backend/app/routes/editor_routes.py |   6 +-
 .../routes/search_source_connectors_routes.py |   1 -
 surfsense_backend/app/schemas/folders.py      |   7 +-
 .../app/tasks/celery_tasks/document_tasks.py  |  15 +-
 .../local_folder_indexer.py                   | 215 +++++++++++++-----
 .../app/utils/document_versioning.py          |   6 +-
 .../tests/integration/conftest.py             |   2 -
 .../test_local_folder_pipeline.py             | 198 +++++++++-------
 .../integration/test_document_versioning.py   |  55 ++---
 .../test_local_folder_scan.py                 |   4 +-
 .../app/(home)/login/LocalLoginForm.tsx       |  20 +-
 surfsense_web/app/(home)/register/page.tsx    | 131 +++++------
 .../(manage)/components/DocumentsFilters.tsx  |  22 +-
 .../components/PromptsContent.tsx             |   7 +-
 .../assistant-ui/connector-popup.tsx          |   5 +-
 .../views/connector-edit-view.tsx             |  58 ++---
 .../assistant-ui/document-upload-popup.tsx    |   5 +-
 .../assistant-ui/inline-citation.tsx          |   3 +-
 .../components/documents/DocumentNode.tsx     |  17 +-
 .../components/documents/FolderNode.tsx       | 186 +++++++--------
 .../components/documents/FolderTreeView.tsx   |   8 +-
 .../components/documents/version-history.tsx  |  42 ++--
 .../components/editor-panel/editor-panel.tsx  |  39 ++--
 .../layout/ui/sidebar/DocumentsSidebar.tsx    | 185 ++++++++-------
 .../layout/ui/tabs/DocumentTabContent.tsx     |   4 +-
 .../new-chat/source-detail-panel.tsx          |   4 +-
 .../components/settings/llm-role-manager.tsx  |  41 ++--
 .../components/sources/DocumentUploadTab.tsx  |  73 +++---
 .../lib/apis/connectors-api.service.ts        |   1 -
 .../lib/apis/documents-api.service.ts         |  38 +++-
 31 files changed, 801 insertions(+), 660 deletions(-)

diff --git a/surfsense_backend/app/routes/documents_routes.py b/surfsense_backend/app/routes/documents_routes.py
index c86cdab3f..5008b1a10 100644
--- a/surfsense_backend/app/routes/documents_routes.py
+++ b/surfsense_backend/app/routes/documents_routes.py
@@ -977,15 +977,19 @@ async def get_watched_folders(
     )
 
     folders = (
-        await session.execute(
-            select(Folder).where(
-                Folder.search_space_id == search_space_id,
-                Folder.parent_id.is_(None),
-                Folder.folder_metadata.isnot(None),
-                Folder.folder_metadata["watched"].astext == "true",
+        (
+            await session.execute(
+                select(Folder).where(
+                    Folder.search_space_id == search_space_id,
+                    Folder.parent_id.is_(None),
+                    Folder.folder_metadata.isnot(None),
+                    Folder.folder_metadata["watched"].astext == "true",
+                )
             )
         )
-    ).scalars().all()
+        .scalars()
+        .all()
+    )
 
     return folders
 
@@ -1265,15 +1269,21 @@ async def list_document_versions(
     if not document:
         raise HTTPException(status_code=404, detail="Document not found")
 
-    await check_permission(session, user, document.search_space_id, Permission.DOCUMENTS_READ.value)
+    await check_permission(
+        session, user, document.search_space_id, Permission.DOCUMENTS_READ.value
+    )
 
     versions = (
-        await session.execute(
-            select(DocumentVersion)
-            .where(DocumentVersion.document_id == document_id)
-            .order_by(DocumentVersion.version_number.desc())
+        (
+            await session.execute(
+                select(DocumentVersion)
+                .where(DocumentVersion.document_id == document_id)
+                .order_by(DocumentVersion.version_number.desc())
+            )
         )
-    ).scalars().all()
+        .scalars()
+        .all()
+    )
 
     return [
         {
@@ -1300,7 +1310,9 @@ async def get_document_version(
     if not document:
         raise HTTPException(status_code=404, detail="Document not found")
 
-    await check_permission(session, user, document.search_space_id, Permission.DOCUMENTS_READ.value)
+    await check_permission(
+        session, user, document.search_space_id, Permission.DOCUMENTS_READ.value
+    )
 
     version = (
         await session.execute(
@@ -1331,14 +1343,14 @@ async def restore_document_version(
 ):
     """Restore a previous version: snapshot current state, then overwrite document content."""
     document = (
-        await session.execute(
-            select(Document).where(Document.id == document_id)
-        )
+        await session.execute(select(Document).where(Document.id == document_id))
     ).scalar_one_or_none()
     if not document:
         raise HTTPException(status_code=404, detail="Document not found")
 
-    await check_permission(session, user, document.search_space_id, Permission.DOCUMENTS_UPDATE.value)
+    await check_permission(
+        session, user, document.search_space_id, Permission.DOCUMENTS_UPDATE.value
+    )
 
     version = (
         await session.execute(
@@ -1363,6 +1375,7 @@ async def restore_document_version(
     await session.commit()
 
     from app.tasks.celery_tasks.document_reindex_tasks import reindex_document_task
+
     reindex_document_task.delay(document_id, str(user.id))
 
     return {
@@ -1430,9 +1443,7 @@ async def folder_index(
     root_folder_id = request.root_folder_id
     if root_folder_id:
         existing = (
-            await session.execute(
-                select(Folder).where(Folder.id == root_folder_id)
-            )
+            await session.execute(select(Folder).where(Folder.id == root_folder_id))
         ).scalar_one_or_none()
         if not existing:
             root_folder_id = None
@@ -1492,7 +1503,9 @@ async def folder_index_files(
         )
 
     if not request.target_file_paths:
-        raise HTTPException(status_code=400, detail="target_file_paths must not be empty")
+        raise HTTPException(
+            status_code=400, detail="target_file_paths must not be empty"
+        )
 
     await check_permission(
         session,
@@ -1507,11 +1520,11 @@ async def folder_index_files(
     for fp in request.target_file_paths:
         try:
             Path(fp).relative_to(request.folder_path)
-        except ValueError:
+        except ValueError as err:
             raise HTTPException(
                 status_code=400,
                 detail=f"target_file_path {fp} must be inside folder_path",
-            )
+            ) from err
 
     from app.tasks.celery_tasks.document_tasks import index_local_folder_task
 
@@ -1530,5 +1543,3 @@ async def folder_index_files(
         "status": "processing",
         "file_count": len(request.target_file_paths),
     }
-
-
diff --git a/surfsense_backend/app/routes/editor_routes.py b/surfsense_backend/app/routes/editor_routes.py
index a0505f62f..829b2cf69 100644
--- a/surfsense_backend/app/routes/editor_routes.py
+++ b/surfsense_backend/app/routes/editor_routes.py
@@ -129,7 +129,11 @@ async def get_editor_content(
 
     if not chunk_contents:
         doc_status = document.status or {}
-        state = doc_status.get("state", "ready") if isinstance(doc_status, dict) else "ready"
+        state = (
+            doc_status.get("state", "ready")
+            if isinstance(doc_status, dict)
+            else "ready"
+        )
         if state in ("pending", "processing"):
             raise HTTPException(
                 status_code=409,
diff --git a/surfsense_backend/app/routes/search_source_connectors_routes.py b/surfsense_backend/app/routes/search_source_connectors_routes.py
index f49ba2d5d..d208ff910 100644
--- a/surfsense_backend/app/routes/search_source_connectors_routes.py
+++ b/surfsense_backend/app/routes/search_source_connectors_routes.py
@@ -20,7 +20,6 @@ Non-OAuth connectors (BookStack, GitHub, etc.) are limited to one per search spa
 
 import asyncio
 import logging
-import os
 from contextlib import suppress
 from datetime import UTC, datetime, timedelta
 from typing import Any
diff --git a/surfsense_backend/app/schemas/folders.py b/surfsense_backend/app/schemas/folders.py
index e8bdf3821..a7e065144 100644
--- a/surfsense_backend/app/schemas/folders.py
+++ b/surfsense_backend/app/schemas/folders.py
@@ -1,9 +1,8 @@
 """Pydantic schemas for folder CRUD, move, and reorder operations."""
 
 from datetime import datetime
-from uuid import UUID
-
 from typing import Any
+from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -36,7 +35,9 @@ class FolderRead(BaseModel):
     created_by_id: UUID | None
     created_at: datetime
     updated_at: datetime
-    metadata: dict[str, Any] | None = Field(default=None, validation_alias="folder_metadata")
+    metadata: dict[str, Any] | None = Field(
+        default=None, validation_alias="folder_metadata"
+    )
 
     model_config = ConfigDict(from_attributes=True)
 
diff --git a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
index 506f8118c..4e9249d34 100644
--- a/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
+++ b/surfsense_backend/app/tasks/celery_tasks/document_tasks.py
@@ -1,6 +1,7 @@
 """Celery tasks for document processing."""
 
 import asyncio
+import contextlib
 import logging
 import os
 from uuid import UUID
@@ -1337,9 +1338,7 @@ async def _index_local_folder_async(
             )
             notification_id = notification.id
             _start_heartbeat(notification_id)
-            heartbeat_task = asyncio.create_task(
-                _run_heartbeat_loop(notification_id)
-            )
+            heartbeat_task = asyncio.create_task(_run_heartbeat_loop(notification_id))
         except Exception:
             logger.warning(
                 "Failed to create notification for local folder indexing",
@@ -1349,18 +1348,16 @@ async def _index_local_folder_async(
         async def _heartbeat_progress(completed_count: int) -> None:
             """Refresh heartbeat and optionally update notification progress."""
             if notification:
-                try:
+                with contextlib.suppress(Exception):
                     await NotificationService.document_processing.notify_processing_progress(
                         session=session,
                         notification=notification,
                         stage="indexing",
                         stage_message=f"Syncing files ({completed_count}/{file_count or '?'})",
                     )
-                except Exception:
-                    pass
 
         try:
-            indexed, skipped_or_failed, _rfid, err = await index_local_folder(
+            _indexed, _skipped_or_failed, _rfid, err = await index_local_folder(
                 session=session,
                 search_space_id=search_space_id,
                 user_id=user_id,
@@ -1371,7 +1368,9 @@ async def _index_local_folder_async(
                 root_folder_id=root_folder_id,
                 enable_summary=enable_summary,
                 target_file_paths=target_file_paths,
-                on_heartbeat_callback=_heartbeat_progress if (is_batch or is_full_scan) else None,
+                on_heartbeat_callback=_heartbeat_progress
+                if (is_batch or is_full_scan)
+                else None,
             )
 
             if notification:
diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index 4ac8cc594..539cfdd32 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -43,30 +43,110 @@ from .base import (
     logger,
 )
 
-PLAINTEXT_EXTENSIONS = frozenset({
-    ".md", ".markdown", ".txt", ".text", ".csv", ".tsv",
-    ".json", ".jsonl", ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf",
-    ".xml", ".html", ".htm", ".css", ".scss", ".less", ".sass",
-    ".py", ".pyw", ".pyi", ".pyx",
-    ".js", ".jsx", ".ts", ".tsx", ".mjs", ".cjs",
-    ".java", ".kt", ".kts", ".scala", ".groovy",
-    ".c", ".h", ".cpp", ".cxx", ".cc", ".hpp", ".hxx",
-    ".cs", ".fs", ".fsx",
-    ".go", ".rs", ".rb", ".php", ".pl", ".pm", ".lua",
-    ".swift", ".m", ".mm",
-    ".r", ".R", ".jl",
-    ".sh", ".bash", ".zsh", ".fish", ".bat", ".cmd", ".ps1",
-    ".sql", ".graphql", ".gql",
-    ".env", ".gitignore", ".dockerignore", ".editorconfig",
-    ".makefile", ".cmake",
-    ".log", ".rst", ".tex", ".bib", ".org", ".adoc", ".asciidoc",
-    ".vue", ".svelte", ".astro",
-    ".tf", ".hcl", ".proto",
-})
+PLAINTEXT_EXTENSIONS = frozenset(
+    {
+        ".md",
+        ".markdown",
+        ".txt",
+        ".text",
+        ".csv",
+        ".tsv",
+        ".json",
+        ".jsonl",
+        ".yaml",
+        ".yml",
+        ".toml",
+        ".ini",
+        ".cfg",
+        ".conf",
+        ".xml",
+        ".html",
+        ".htm",
+        ".css",
+        ".scss",
+        ".less",
+        ".sass",
+        ".py",
+        ".pyw",
+        ".pyi",
+        ".pyx",
+        ".js",
+        ".jsx",
+        ".ts",
+        ".tsx",
+        ".mjs",
+        ".cjs",
+        ".java",
+        ".kt",
+        ".kts",
+        ".scala",
+        ".groovy",
+        ".c",
+        ".h",
+        ".cpp",
+        ".cxx",
+        ".cc",
+        ".hpp",
+        ".hxx",
+        ".cs",
+        ".fs",
+        ".fsx",
+        ".go",
+        ".rs",
+        ".rb",
+        ".php",
+        ".pl",
+        ".pm",
+        ".lua",
+        ".swift",
+        ".m",
+        ".mm",
+        ".r",
+        ".R",
+        ".jl",
+        ".sh",
+        ".bash",
+        ".zsh",
+        ".fish",
+        ".bat",
+        ".cmd",
+        ".ps1",
+        ".sql",
+        ".graphql",
+        ".gql",
+        ".env",
+        ".gitignore",
+        ".dockerignore",
+        ".editorconfig",
+        ".makefile",
+        ".cmake",
+        ".log",
+        ".rst",
+        ".tex",
+        ".bib",
+        ".org",
+        ".adoc",
+        ".asciidoc",
+        ".vue",
+        ".svelte",
+        ".astro",
+        ".tf",
+        ".hcl",
+        ".proto",
+    }
+)
 
-AUDIO_EXTENSIONS = frozenset({
-    ".mp3", ".mp4", ".mpeg", ".mpga", ".m4a", ".wav", ".webm",
-})
+AUDIO_EXTENSIONS = frozenset(
+    {
+        ".mp3",
+        ".mp4",
+        ".mpeg",
+        ".mpga",
+        ".m4a",
+        ".wav",
+        ".webm",
+    }
+)
 
 
 def _is_plaintext_file(filename: str) -> bool:
@@ -81,6 +161,7 @@ def _needs_etl(filename: str) -> bool:
     """File is not plaintext and not audio — requires ETL service to parse."""
     return not _is_plaintext_file(filename) and not _is_audio_file(filename)
 
+
 HeartbeatCallbackType = Callable[[int], Awaitable[None]]
 
 DEFAULT_EXCLUDE_PATTERNS = [
@@ -121,9 +202,7 @@ def scan_folder(
     for dirpath, dirnames, filenames in os.walk(root):
         rel_dir = Path(dirpath).relative_to(root)
 
-        dirnames[:] = [
-            d for d in dirnames if d not in exclude_patterns
-        ]
+        dirnames[:] = [d for d in dirnames if d not in exclude_patterns]
 
         if any(part in exclude_patterns for part in rel_dir.parts):
             continue
@@ -134,9 +213,11 @@ def scan_folder(
 
             full = Path(dirpath) / fname
 
-            if file_extensions is not None:
-                if full.suffix.lower() not in file_extensions:
-                    continue
+            if (
+                file_extensions is not None
+                and full.suffix.lower() not in file_extensions
+            ):
+                continue
 
             try:
                 stat = full.stat()
@@ -209,11 +290,14 @@ def _content_hash(content: str, search_space_id: int) -> str:
     pipeline so that dedup checks are consistent.
     """
     import hashlib
-    return hashlib.sha256(f"{search_space_id}:{content}".encode("utf-8")).hexdigest()
+
+    return hashlib.sha256(f"{search_space_id}:{content}".encode()).hexdigest()
 
 
 async def _compute_file_content_hash(
-    file_path: str, filename: str, search_space_id: int,
+    file_path: str,
+    filename: str,
+    search_space_id: int,
 ) -> tuple[str, str]:
     """Read a file (via ETL if needed) and compute its content hash.
 
@@ -257,9 +341,7 @@ async def _mirror_folder_structure(
 
     if root_folder_id:
         existing = (
-            await session.execute(
-                select(Folder).where(Folder.id == root_folder_id)
-            )
+            await session.execute(select(Folder).where(Folder.id == root_folder_id))
         ).scalar_one_or_none()
         if existing:
             mapping[""] = existing.id
@@ -412,13 +494,17 @@ async def _cleanup_empty_folders(
     id_to_rel: dict[int, str] = {fid: rel for rel, fid in folder_mapping.items() if rel}
 
     all_folders = (
-        await session.execute(
-            select(Folder).where(
-                Folder.search_space_id == search_space_id,
-                Folder.id != root_folder_id,
+        (
+            await session.execute(
+                select(Folder).where(
+                    Folder.search_space_id == search_space_id,
+                    Folder.id != root_folder_id,
+                )
             )
         )
-    ).scalars().all()
+        .scalars()
+        .all()
+    )
 
     candidates: list[Folder] = []
     for folder in all_folders:
@@ -520,7 +606,9 @@ async def index_local_folder(
         metadata={
             "folder_path": folder_path,
             "user_id": str(user_id),
-            "target_file_paths_count": len(target_file_paths) if target_file_paths else None,
+            "target_file_paths_count": len(target_file_paths)
+            if target_file_paths
+            else None,
         },
     )
 
@@ -532,7 +620,12 @@ async def index_local_folder(
                 "Folder not found",
                 {},
             )
-            return 0, 0, root_folder_id, f"Folder path missing or does not exist: {folder_path}"
+            return (
+                0,
+                0,
+                root_folder_id,
+                f"Folder path missing or does not exist: {folder_path}",
+            )
 
         if exclude_patterns is None:
             exclude_patterns = DEFAULT_EXCLUDE_PATTERNS
@@ -639,7 +732,9 @@ async def index_local_folder(
                 )
 
                 if existing_document:
-                    stored_mtime = (existing_document.document_metadata or {}).get("mtime")
+                    stored_mtime = (existing_document.document_metadata or {}).get(
+                        "mtime"
+                    )
                     current_mtime = file_info["modified_at"].timestamp()
 
                     if stored_mtime and abs(current_mtime - stored_mtime) < 1.0:
@@ -709,23 +804,31 @@ async def index_local_folder(
         # ================================================================
         all_root_folder_ids = set(folder_mapping.values())
         all_db_folders = (
-            await session.execute(
-                select(Folder.id).where(
-                    Folder.search_space_id == search_space_id,
+            (
+                await session.execute(
+                    select(Folder.id).where(
+                        Folder.search_space_id == search_space_id,
+                    )
                 )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
         all_root_folder_ids.update(all_db_folders)
 
         all_folder_docs = (
-            await session.execute(
-                select(Document).where(
-                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
-                    Document.search_space_id == search_space_id,
-                    Document.folder_id.in_(list(all_root_folder_ids)),
+            (
+                await session.execute(
+                    select(Document).where(
+                        Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                        Document.search_space_id == search_space_id,
+                        Document.folder_id.in_(list(all_root_folder_ids)),
+                    )
                 )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
 
         for doc in all_folder_docs:
             if doc.unique_identifier_hash not in seen_unique_hashes:
@@ -742,9 +845,7 @@ async def index_local_folder(
             )
 
             pipeline = IndexingPipelineService(session)
-            doc_map = {
-                compute_unique_identifier_hash(cd): cd for cd in connector_docs
-            }
+            doc_map = {compute_unique_identifier_hash(cd): cd for cd in connector_docs}
             documents = await pipeline.prepare_for_indexing(connector_docs)
 
             # Assign folder_id immediately so docs appear in the correct
@@ -1033,7 +1134,9 @@ async def _index_single_file(
         db_doc.document_metadata = doc_meta
         await session.commit()
 
-        indexed = 1 if DocumentStatus.is_state(db_doc.status, DocumentStatus.READY) else 0
+        indexed = (
+            1 if DocumentStatus.is_state(db_doc.status, DocumentStatus.READY) else 0
+        )
         failed_msg = None if indexed else "Indexing failed"
 
         if indexed:
diff --git a/surfsense_backend/app/utils/document_versioning.py b/surfsense_backend/app/utils/document_versioning.py
index 889bc4a3a..e6ad1fb06 100644
--- a/surfsense_backend/app/utils/document_versioning.py
+++ b/surfsense_backend/app/utils/document_versioning.py
@@ -83,9 +83,9 @@ async def create_version_snapshot(
     # Cleanup: cap at MAX_VERSIONS_PER_DOCUMENT
     count = (
         await session.execute(
-            select(func.count()).select_from(DocumentVersion).where(
-                DocumentVersion.document_id == document.id
-            )
+            select(func.count())
+            .select_from(DocumentVersion)
+            .where(DocumentVersion.document_id == document.id)
         )
     ).scalar_one()
 
diff --git a/surfsense_backend/tests/integration/conftest.py b/surfsense_backend/tests/integration/conftest.py
index 9c91011ae..d9d7cacae 100644
--- a/surfsense_backend/tests/integration/conftest.py
+++ b/surfsense_backend/tests/integration/conftest.py
@@ -166,5 +166,3 @@ def make_connector_document(db_connector, db_user):
         return ConnectorDocument(**defaults)
 
     return _make
-
-
diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index 67254ec93..4062c3a3b 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -21,7 +21,9 @@ from app.db import (
 pytestmark = pytest.mark.integration
 
 UNIFIED_FIXTURES = (
-    "patched_summarize", "patched_embed_texts", "patched_chunk_text",
+    "patched_summarize",
+    "patched_embed_texts",
+    "patched_chunk_text",
 )
 
 
@@ -37,6 +39,7 @@ class _FakeSessionMaker:
         @asynccontextmanager
         async def _ctx():
             yield self._session
+
         return _ctx()
 
 
@@ -59,7 +62,6 @@ def patched_batch_sessions(monkeypatch, db_session):
 
 
 class TestFullIndexer:
-
     @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_i1_new_file_indexed(
         self,
@@ -73,7 +75,7 @@ class TestFullIndexer:
 
         (tmp_path / "note.md").write_text("# Hello World\n\nContent here.")
 
-        count, skipped, root_folder_id, err = await index_local_folder(
+        count, _skipped, _root_folder_id, err = await index_local_folder(
             session=db_session,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
@@ -85,13 +87,17 @@ class TestFullIndexer:
         assert count == 1
 
         docs = (
-            await db_session.execute(
-                select(Document).where(
-                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
-                    Document.search_space_id == db_search_space.id,
+            (
+                await db_session.execute(
+                    select(Document).where(
+                        Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                        Document.search_space_id == db_search_space.id,
+                    )
                 )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
         assert len(docs) == 1
         assert docs[0].document_type == DocumentType.LOCAL_FOLDER_FILE
         assert DocumentStatus.is_state(docs[0].status, DocumentStatus.READY)
@@ -130,7 +136,9 @@ class TestFullIndexer:
 
         total = (
             await db_session.execute(
-                select(func.count()).select_from(Document).where(
+                select(func.count())
+                .select_from(Document)
+                .where(
                     Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
                     Document.search_space_id == db_search_space.id,
                 )
@@ -174,13 +182,19 @@ class TestFullIndexer:
         assert count == 1
 
         versions = (
-            await db_session.execute(
-                select(DocumentVersion).join(Document).where(
-                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
-                    Document.search_space_id == db_search_space.id,
+            (
+                await db_session.execute(
+                    select(DocumentVersion)
+                    .join(Document)
+                    .where(
+                        Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                        Document.search_space_id == db_search_space.id,
+                    )
                 )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
         assert len(versions) >= 1
 
     @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
@@ -207,7 +221,9 @@ class TestFullIndexer:
 
         docs_before = (
             await db_session.execute(
-                select(func.count()).select_from(Document).where(
+                select(func.count())
+                .select_from(Document)
+                .where(
                     Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
                     Document.search_space_id == db_search_space.id,
                 )
@@ -228,7 +244,9 @@ class TestFullIndexer:
 
         docs_after = (
             await db_session.execute(
-                select(func.count()).select_from(Document).where(
+                select(func.count())
+                .select_from(Document)
+                .where(
                     Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
                     Document.search_space_id == db_search_space.id,
                 )
@@ -262,13 +280,17 @@ class TestFullIndexer:
         assert count == 1
 
         docs = (
-            await db_session.execute(
-                select(Document).where(
-                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
-                    Document.search_space_id == db_search_space.id,
+            (
+                await db_session.execute(
+                    select(Document).where(
+                        Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                        Document.search_space_id == db_search_space.id,
+                    )
                 )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
         assert len(docs) == 1
         assert docs[0].title == "b.md"
 
@@ -279,7 +301,6 @@ class TestFullIndexer:
 
 
 class TestFolderMirroring:
-
     @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_f1_root_folder_created(
         self,
@@ -335,10 +356,14 @@ class TestFolderMirroring:
         )
 
         folders = (
-            await db_session.execute(
-                select(Folder).where(Folder.search_space_id == db_search_space.id)
+            (
+                await db_session.execute(
+                    select(Folder).where(Folder.search_space_id == db_search_space.id)
+                )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
 
         folder_names = {f.name for f in folders}
         assert "notes" in folder_names
@@ -376,10 +401,14 @@ class TestFolderMirroring:
         )
 
         folders_before = (
-            await db_session.execute(
-                select(Folder).where(Folder.search_space_id == db_search_space.id)
+            (
+                await db_session.execute(
+                    select(Folder).where(Folder.search_space_id == db_search_space.id)
+                )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
         ids_before = {f.id for f in folders_before}
 
         await index_local_folder(
@@ -392,10 +421,14 @@ class TestFolderMirroring:
         )
 
         folders_after = (
-            await db_session.execute(
-                select(Folder).where(Folder.search_space_id == db_search_space.id)
+            (
+                await db_session.execute(
+                    select(Folder).where(Folder.search_space_id == db_search_space.id)
+                )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
         ids_after = {f.id for f in folders_after}
 
         assert ids_before == ids_after
@@ -425,21 +458,23 @@ class TestFolderMirroring:
         )
 
         docs = (
-            await db_session.execute(
-                select(Document).where(
-                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
-                    Document.search_space_id == db_search_space.id,
+            (
+                await db_session.execute(
+                    select(Document).where(
+                        Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                        Document.search_space_id == db_search_space.id,
+                    )
                 )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
 
         today_doc = next(d for d in docs if d.title == "today.md")
         root_doc = next(d for d in docs if d.title == "root.md")
 
         daily_folder = (
-            await db_session.execute(
-                select(Folder).where(Folder.name == "daily")
-            )
+            await db_session.execute(select(Folder).where(Folder.name == "daily"))
         ).scalar_one()
 
         assert today_doc.folder_id == daily_folder.id
@@ -455,9 +490,10 @@ class TestFolderMirroring:
         tmp_path: Path,
     ):
         """F5: Deleted dir's empty Folder row is cleaned up on re-sync."""
-        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
         import shutil
 
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
         daily = tmp_path / "notes" / "daily"
         daily.mkdir(parents=True)
         weekly = tmp_path / "notes" / "weekly"
@@ -474,9 +510,7 @@ class TestFolderMirroring:
         )
 
         weekly_folder = (
-            await db_session.execute(
-                select(Folder).where(Folder.name == "weekly")
-            )
+            await db_session.execute(select(Folder).where(Folder.name == "weekly"))
         ).scalar_one_or_none()
         assert weekly_folder is not None
 
@@ -492,16 +526,12 @@ class TestFolderMirroring:
         )
 
         weekly_after = (
-            await db_session.execute(
-                select(Folder).where(Folder.name == "weekly")
-            )
+            await db_session.execute(select(Folder).where(Folder.name == "weekly"))
         ).scalar_one_or_none()
         assert weekly_after is None
 
         daily_after = (
-            await db_session.execute(
-                select(Folder).where(Folder.name == "daily")
-            )
+            await db_session.execute(select(Folder).where(Folder.name == "daily"))
         ).scalar_one_or_none()
         assert daily_after is not None
 
@@ -551,18 +581,14 @@ class TestFolderMirroring:
         ).scalar_one()
 
         daily_folder = (
-            await db_session.execute(
-                select(Folder).where(Folder.name == "daily")
-            )
+            await db_session.execute(select(Folder).where(Folder.name == "daily"))
         ).scalar_one()
 
         assert doc.folder_id == daily_folder.id
         assert daily_folder.parent_id is not None
 
         notes_folder = (
-            await db_session.execute(
-                select(Folder).where(Folder.name == "notes")
-            )
+            await db_session.execute(select(Folder).where(Folder.name == "notes"))
         ).scalar_one()
         assert daily_folder.parent_id == notes_folder.id
         assert notes_folder.parent_id == root_folder_id
@@ -592,9 +618,7 @@ class TestFolderMirroring:
         )
 
         eph_folder = (
-            await db_session.execute(
-                select(Folder).where(Folder.name == "ephemeral")
-            )
+            await db_session.execute(select(Folder).where(Folder.name == "ephemeral"))
         ).scalar_one_or_none()
         assert eph_folder is not None
 
@@ -612,16 +636,12 @@ class TestFolderMirroring:
         )
 
         eph_after = (
-            await db_session.execute(
-                select(Folder).where(Folder.name == "ephemeral")
-            )
+            await db_session.execute(select(Folder).where(Folder.name == "ephemeral"))
         ).scalar_one_or_none()
         assert eph_after is None
 
         notes_after = (
-            await db_session.execute(
-                select(Folder).where(Folder.name == "notes")
-            )
+            await db_session.execute(select(Folder).where(Folder.name == "notes"))
         ).scalar_one_or_none()
         assert notes_after is None
 
@@ -632,7 +652,6 @@ class TestFolderMirroring:
 
 
 class TestBatchMode:
-
     @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_b1_batch_indexes_multiple_files(
         self,
@@ -649,7 +668,7 @@ class TestBatchMode:
         (tmp_path / "b.md").write_text("File B content")
         (tmp_path / "c.md").write_text("File C content")
 
-        count, failed, root_folder_id, err = await index_local_folder(
+        count, failed, _root_folder_id, err = await index_local_folder(
             session=db_session,
             search_space_id=db_search_space.id,
             user_id=str(db_user.id),
@@ -667,13 +686,17 @@ class TestBatchMode:
         assert err is None
 
         docs = (
-            await db_session.execute(
-                select(Document).where(
-                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
-                    Document.search_space_id == db_search_space.id,
+            (
+                await db_session.execute(
+                    select(Document).where(
+                        Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                        Document.search_space_id == db_search_space.id,
+                    )
                 )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
         assert len(docs) == 3
         assert {d.title for d in docs} == {"a.md", "b.md", "c.md"}
         assert all(
@@ -714,13 +737,17 @@ class TestBatchMode:
         assert err is not None
 
         docs = (
-            await db_session.execute(
-                select(Document).where(
-                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
-                    Document.search_space_id == db_search_space.id,
+            (
+                await db_session.execute(
+                    select(Document).where(
+                        Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                        Document.search_space_id == db_search_space.id,
+                    )
                 )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
         assert len(docs) == 2
         assert {d.title for d in docs} == {"good1.md", "good2.md"}
 
@@ -731,7 +758,6 @@ class TestBatchMode:
 
 
 class TestPipelineIntegration:
-
     @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
     async def test_p1_local_folder_file_through_pipeline(
         self,
@@ -742,7 +768,9 @@ class TestPipelineIntegration:
     ):
         """P1: LOCAL_FOLDER_FILE ConnectorDocument through prepare+index to READY."""
         from app.indexing_pipeline.connector_document import ConnectorDocument
-        from app.indexing_pipeline.indexing_pipeline_service import IndexingPipelineService
+        from app.indexing_pipeline.indexing_pipeline_service import (
+            IndexingPipelineService,
+        )
 
         doc = ConnectorDocument(
             title="Test Local File",
@@ -763,12 +791,16 @@ class TestPipelineIntegration:
         assert result is not None
 
         docs = (
-            await db_session.execute(
-                select(Document).where(
-                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
-                    Document.search_space_id == db_search_space.id,
+            (
+                await db_session.execute(
+                    select(Document).where(
+                        Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                        Document.search_space_id == db_search_space.id,
+                    )
                 )
             )
-        ).scalars().all()
+            .scalars()
+            .all()
+        )
         assert len(docs) == 1
         assert DocumentStatus.is_state(docs[0].status, DocumentStatus.READY)
diff --git a/surfsense_backend/tests/integration/test_document_versioning.py b/surfsense_backend/tests/integration/test_document_versioning.py
index 87e3c490c..9bd03d219 100644
--- a/surfsense_backend/tests/integration/test_document_versioning.py
+++ b/surfsense_backend/tests/integration/test_document_versioning.py
@@ -34,14 +34,16 @@ async def db_document(
 
 async def _version_count(session: AsyncSession, document_id: int) -> int:
     result = await session.execute(
-        select(func.count()).select_from(DocumentVersion).where(
-            DocumentVersion.document_id == document_id
-        )
+        select(func.count())
+        .select_from(DocumentVersion)
+        .where(DocumentVersion.document_id == document_id)
     )
     return result.scalar_one()
 
 
-async def _get_versions(session: AsyncSession, document_id: int) -> list[DocumentVersion]:
+async def _get_versions(
+    session: AsyncSession, document_id: int
+) -> list[DocumentVersion]:
     result = await session.execute(
         select(DocumentVersion)
         .where(DocumentVersion.document_id == document_id)
@@ -74,18 +76,14 @@ class TestCreateVersionSnapshot:
         from app.utils.document_versioning import create_version_snapshot
 
         t0 = datetime(2025, 1, 1, 12, 0, 0, tzinfo=UTC)
-        monkeypatch.setattr(
-            "app.utils.document_versioning._now", lambda: t0
-        )
+        monkeypatch.setattr("app.utils.document_versioning._now", lambda: t0)
         await create_version_snapshot(db_session, db_document)
 
         # Simulate content change and time passing
         db_document.source_markdown = "# Test\n\nUpdated content."
         db_document.content_hash = "def456"
         t1 = t0 + timedelta(minutes=31)
-        monkeypatch.setattr(
-            "app.utils.document_versioning._now", lambda: t1
-        )
+        monkeypatch.setattr("app.utils.document_versioning._now", lambda: t1)
         await create_version_snapshot(db_session, db_document)
 
         versions = await _get_versions(db_session, db_document.id)
@@ -101,9 +99,7 @@ class TestCreateVersionSnapshot:
         from app.utils.document_versioning import create_version_snapshot
 
         t0 = datetime(2025, 1, 1, 12, 0, 0, tzinfo=UTC)
-        monkeypatch.setattr(
-            "app.utils.document_versioning._now", lambda: t0
-        )
+        monkeypatch.setattr("app.utils.document_versioning._now", lambda: t0)
         await create_version_snapshot(db_session, db_document)
         count_after_first = await _version_count(db_session, db_document.id)
         assert count_after_first == 1
@@ -112,9 +108,7 @@ class TestCreateVersionSnapshot:
         db_document.source_markdown = "# Test\n\nQuick edit."
         db_document.content_hash = "quick123"
         t1 = t0 + timedelta(minutes=10)
-        monkeypatch.setattr(
-            "app.utils.document_versioning._now", lambda: t1
-        )
+        monkeypatch.setattr("app.utils.document_versioning._now", lambda: t1)
         await create_version_snapshot(db_session, db_document)
 
         count_after_second = await _version_count(db_session, db_document.id)
@@ -134,22 +128,15 @@ class TestCreateVersionSnapshot:
 
         # Create 5 versions spread across time: 3 older than 90 days, 2 recent
         for i in range(5):
-            db_document.source_markdown = f"Content v{i+1}"
-            db_document.content_hash = f"hash_{i+1}"
-            if i < 3:
-                t = base + timedelta(days=i)  # old
-            else:
-                t = base + timedelta(days=100 + i)  # recent
-            monkeypatch.setattr(
-                "app.utils.document_versioning._now", lambda _t=t: _t
-            )
+            db_document.source_markdown = f"Content v{i + 1}"
+            db_document.content_hash = f"hash_{i + 1}"
+            t = base + timedelta(days=i) if i < 3 else base + timedelta(days=100 + i)
+            monkeypatch.setattr("app.utils.document_versioning._now", lambda _t=t: _t)
             await create_version_snapshot(db_session, db_document)
 
         # Now trigger cleanup from a "current" time that makes the first 3 versions > 90 days old
         now = base + timedelta(days=200)
-        monkeypatch.setattr(
-            "app.utils.document_versioning._now", lambda: now
-        )
+        monkeypatch.setattr("app.utils.document_versioning._now", lambda: now)
         db_document.source_markdown = "Content v6"
         db_document.content_hash = "hash_6"
         await create_version_snapshot(db_session, db_document)
@@ -160,9 +147,7 @@ class TestCreateVersionSnapshot:
             age = now - v.created_at.replace(tzinfo=UTC)
             assert age <= timedelta(days=90), f"Version {v.version_number} is too old"
 
-    async def test_v5_cap_at_20_versions(
-        self, db_session, db_document, monkeypatch
-    ):
+    async def test_v5_cap_at_20_versions(self, db_session, db_document, monkeypatch):
         """V5: More than 20 versions triggers cap — oldest gets deleted."""
         from app.utils.document_versioning import create_version_snapshot
 
@@ -170,12 +155,10 @@ class TestCreateVersionSnapshot:
 
         # Create 21 versions (all within 90 days, each 31 min apart)
         for i in range(21):
-            db_document.source_markdown = f"Content v{i+1}"
-            db_document.content_hash = f"hash_{i+1}"
+            db_document.source_markdown = f"Content v{i + 1}"
+            db_document.content_hash = f"hash_{i + 1}"
             t = base + timedelta(minutes=31 * i)
-            monkeypatch.setattr(
-                "app.utils.document_versioning._now", lambda _t=t: _t
-            )
+            monkeypatch.setattr("app.utils.document_versioning._now", lambda _t=t: _t)
             await create_version_snapshot(db_session, db_document)
 
         versions = await _get_versions(db_session, db_document.id)
diff --git a/surfsense_backend/tests/unit/connector_indexers/test_local_folder_scan.py b/surfsense_backend/tests/unit/connector_indexers/test_local_folder_scan.py
index 9b4c73f25..c6e7b160c 100644
--- a/surfsense_backend/tests/unit/connector_indexers/test_local_folder_scan.py
+++ b/surfsense_backend/tests/unit/connector_indexers/test_local_folder_scan.py
@@ -51,9 +51,7 @@ class TestScanFolder:
         git.mkdir()
         (git / "config").write_text("gitconfig")
 
-        results = scan_folder(
-            str(tmp_path), exclude_patterns=["node_modules", ".git"]
-        )
+        results = scan_folder(str(tmp_path), exclude_patterns=["node_modules", ".git"])
         names = {r["relative_path"] for r in results}
 
         assert "good.md" in names
diff --git a/surfsense_web/app/(home)/login/LocalLoginForm.tsx b/surfsense_web/app/(home)/login/LocalLoginForm.tsx
index 1ebbf46b6..e94857334 100644
--- a/surfsense_web/app/(home)/login/LocalLoginForm.tsx
+++ b/surfsense_web/app/(home)/login/LocalLoginForm.tsx
@@ -160,11 +160,11 @@ export function LocalLoginForm() {
 						placeholder="you@example.com"
 						value={username}
 						onChange={(e) => setUsername(e.target.value)}
-					className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
-						error.title
-							? "border-destructive focus:border-destructive focus:ring-destructive/40"
-							: "border-border focus:border-primary focus:ring-primary/40"
-					}`}
+						className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+							error.title
+								? "border-destructive focus:border-destructive focus:ring-destructive/40"
+								: "border-border focus:border-primary focus:ring-primary/40"
+						}`}
 						disabled={isLoggingIn}
 					/>
 				</div>
@@ -181,11 +181,11 @@ export function LocalLoginForm() {
 							placeholder="Enter your password"
 							value={password}
 							onChange={(e) => setPassword(e.target.value)}
-						className={`mt-1 block w-full rounded-md border pr-10 px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
-							error.title
-								? "border-destructive focus:border-destructive focus:ring-destructive/40"
-								: "border-border focus:border-primary focus:ring-primary/40"
-						}`}
+							className={`mt-1 block w-full rounded-md border pr-10 px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+								error.title
+									? "border-destructive focus:border-destructive focus:ring-destructive/40"
+									: "border-border focus:border-primary focus:ring-primary/40"
+							}`}
 							disabled={isLoggingIn}
 						/>
 						<button
diff --git a/surfsense_web/app/(home)/register/page.tsx b/surfsense_web/app/(home)/register/page.tsx
index 3161da4a7..a6926dc5c 100644
--- a/surfsense_web/app/(home)/register/page.tsx
+++ b/surfsense_web/app/(home)/register/page.tsx
@@ -229,72 +229,66 @@ export default function RegisterPage() {
 						</AnimatePresence>
 
 						<div>
-						<label
-							htmlFor="email"
-							className="block text-sm font-medium text-foreground"
-						>
-							{t("email")}
-						</label>
-						<input
-							id="email"
-							type="email"
-							required
-							placeholder="you@example.com"
-							value={email}
-							onChange={(e) => setEmail(e.target.value)}
-						className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
-							error.title
-								? "border-destructive focus:border-destructive focus:ring-destructive/40"
-								: "border-border focus:border-primary focus:ring-primary/40"
-						}`}
-						disabled={isRegistering}
-					/>
-					</div>
+							<label htmlFor="email" className="block text-sm font-medium text-foreground">
+								{t("email")}
+							</label>
+							<input
+								id="email"
+								type="email"
+								required
+								placeholder="you@example.com"
+								value={email}
+								onChange={(e) => setEmail(e.target.value)}
+								className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+									error.title
+										? "border-destructive focus:border-destructive focus:ring-destructive/40"
+										: "border-border focus:border-primary focus:ring-primary/40"
+								}`}
+								disabled={isRegistering}
+							/>
+						</div>
 
-					<div>
-						<label
-							htmlFor="password"
-							className="block text-sm font-medium text-foreground"
-						>
-							{t("password")}
-						</label>
-						<input
-							id="password"
-							type="password"
-							required
-							placeholder="Enter your password"
-							value={password}
-							onChange={(e) => setPassword(e.target.value)}
-							className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
-								error.title
-									? "border-destructive focus:border-destructive focus:ring-destructive/40"
-									: "border-border focus:border-primary focus:ring-primary/40"
-							}`}
-							disabled={isRegistering}
-						/>
-					</div>
+						<div>
+							<label htmlFor="password" className="block text-sm font-medium text-foreground">
+								{t("password")}
+							</label>
+							<input
+								id="password"
+								type="password"
+								required
+								placeholder="Enter your password"
+								value={password}
+								onChange={(e) => setPassword(e.target.value)}
+								className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+									error.title
+										? "border-destructive focus:border-destructive focus:ring-destructive/40"
+										: "border-border focus:border-primary focus:ring-primary/40"
+								}`}
+								disabled={isRegistering}
+							/>
+						</div>
 
-					<div>
-						<label
-							htmlFor="confirmPassword"
-							className="block text-sm font-medium text-foreground"
-						>
-							{t("confirm_password")}
-						</label>
-						<input
-							id="confirmPassword"
-							type="password"
-							required
-							placeholder="Confirm your password"
-							value={confirmPassword}
-							onChange={(e) => setConfirmPassword(e.target.value)}
-							className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
-								error.title
-									? "border-destructive focus:border-destructive focus:ring-destructive/40"
-									: "border-border focus:border-primary focus:ring-primary/40"
-							}`}
-							disabled={isRegistering}
-						/>
+						<div>
+							<label
+								htmlFor="confirmPassword"
+								className="block text-sm font-medium text-foreground"
+							>
+								{t("confirm_password")}
+							</label>
+							<input
+								id="confirmPassword"
+								type="password"
+								required
+								placeholder="Confirm your password"
+								value={confirmPassword}
+								onChange={(e) => setConfirmPassword(e.target.value)}
+								className={`mt-1 block w-full rounded-md border px-3 py-1.5 md:py-2 shadow-sm focus:outline-none focus:ring-1 bg-background text-foreground transition-all ${
+									error.title
+										? "border-destructive focus:border-destructive focus:ring-destructive/40"
+										: "border-border focus:border-primary focus:ring-primary/40"
+								}`}
+								disabled={isRegistering}
+							/>
 						</div>
 
 						<button
@@ -312,12 +306,9 @@ export default function RegisterPage() {
 					</form>
 
 					<div className="mt-4 text-center text-sm">
-					<p className="text-muted-foreground">
-						{t("already_have_account")}{" "}
-						<Link
-							href="/login"
-							className="font-medium text-primary hover:text-primary/90"
-						>
+						<p className="text-muted-foreground">
+							{t("already_have_account")}{" "}
+							<Link href="/login" className="font-medium text-primary hover:text-primary/90">
 								{t("sign_in")}
 							</Link>
 						</p>
diff --git a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx
index 150c119de..b85af13b7 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/documents/(manage)/components/DocumentsFilters.tsx
@@ -214,17 +214,17 @@ export function DocumentsFilters({
 					</Tooltip>
 				)}
 
-		{/* Upload Button */}
-			<Button
-				data-joyride="upload-button"
-				onClick={openUploadDialog}
-				variant="outline"
-				size="sm"
-				className="h-9 shrink-0 gap-1.5 bg-white text-gray-700 border-white hover:bg-gray-50 dark:bg-white dark:text-gray-800 dark:hover:bg-gray-100"
-			>
-				<Upload size={14} />
-				<span>Upload</span>
-			</Button>
+				{/* Upload Button */}
+				<Button
+					data-joyride="upload-button"
+					onClick={openUploadDialog}
+					variant="outline"
+					size="sm"
+					className="h-9 shrink-0 gap-1.5 bg-white text-gray-700 border-white hover:bg-gray-50 dark:bg-white dark:text-gray-800 dark:hover:bg-gray-100"
+				>
+					<Upload size={14} />
+					<span>Upload</span>
+				</Button>
 			</div>
 		</div>
 	);
diff --git a/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/PromptsContent.tsx b/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/PromptsContent.tsx
index 39362d244..1e7087afc 100644
--- a/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/PromptsContent.tsx
+++ b/surfsense_web/app/dashboard/[search_space_id]/user-settings/components/PromptsContent.tsx
@@ -2,7 +2,6 @@
 
 import { useAtomValue } from "jotai";
 import { AlertTriangle, Globe, Lock, PenLine, Sparkles, Trash2 } from "lucide-react";
-import { ShortcutKbd } from "@/components/ui/shortcut-kbd";
 import { useCallback, useState } from "react";
 import { toast } from "sonner";
 import {
@@ -24,6 +23,7 @@ import {
 import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
+import { ShortcutKbd } from "@/components/ui/shortcut-kbd";
 import { Spinner } from "@/components/ui/spinner";
 import { Switch } from "@/components/ui/switch";
 import type { PromptRead } from "@/contracts/types/prompts.types";
@@ -145,9 +145,8 @@ export function PromptsContent() {
 		<div className="space-y-6 min-w-0 overflow-hidden">
 			<div className="flex items-center justify-between">
 				<p className="text-sm text-muted-foreground">
-					Create prompt templates triggered with{" "}
-					<ShortcutKbd keys={["/"]} className="ml-0" /> in the
-					chat composer.
+					Create prompt templates triggered with <ShortcutKbd keys={["/"]} className="ml-0" /> in
+					the chat composer.
 				</p>
 				{!showForm && (
 					<Button
diff --git a/surfsense_web/components/assistant-ui/connector-popup.tsx b/surfsense_web/components/assistant-ui/connector-popup.tsx
index abe623c82..fe7b29f28 100644
--- a/surfsense_web/components/assistant-ui/connector-popup.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup.tsx
@@ -374,7 +374,10 @@ export const ConnectorIndicator = forwardRef<ConnectorIndicatorHandle, Connector
 									<div className="px-4 sm:px-12 py-4 sm:py-8 pb-12 sm:pb-16">
 										{/* LLM Configuration Warning */}
 										{!llmConfigLoading && !hasDocumentSummaryLLM && (
-											<Alert variant="destructive" className="mb-6 bg-muted/50 rounded-xl border-destructive/30">
+											<Alert
+												variant="destructive"
+												className="mb-6 bg-muted/50 rounded-xl border-destructive/30"
+											>
 												<AlertTriangle className="h-4 w-4" />
 												<AlertTitle>LLM Configuration Required</AlertTitle>
 												<AlertDescription className="mt-2">
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx
index 05d42adcb..1e71b0a25 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/views/connector-edit-view.tsx
@@ -294,36 +294,36 @@ export const ConnectorEditView: FC<ConnectorEditViewProps> = ({
 									)}
 
 								{(() => {
-										const isGoogleDrive = connector.connector_type === "GOOGLE_DRIVE_CONNECTOR";
-										const isComposioGoogleDrive =
-											connector.connector_type === "COMPOSIO_GOOGLE_DRIVE_CONNECTOR";
-										const requiresFolderSelection = isGoogleDrive || isComposioGoogleDrive;
-										const selectedFolders =
-											(connector.config?.selected_folders as
-												| Array<{ id: string; name: string }>
-												| undefined) || [];
-										const selectedFiles =
-											(connector.config?.selected_files as
-												| Array<{ id: string; name: string }>
-												| undefined) || [];
-										const hasItemsSelected = selectedFolders.length > 0 || selectedFiles.length > 0;
-										const isDisabled = requiresFolderSelection && !hasItemsSelected;
+									const isGoogleDrive = connector.connector_type === "GOOGLE_DRIVE_CONNECTOR";
+									const isComposioGoogleDrive =
+										connector.connector_type === "COMPOSIO_GOOGLE_DRIVE_CONNECTOR";
+									const requiresFolderSelection = isGoogleDrive || isComposioGoogleDrive;
+									const selectedFolders =
+										(connector.config?.selected_folders as
+											| Array<{ id: string; name: string }>
+											| undefined) || [];
+									const selectedFiles =
+										(connector.config?.selected_files as
+											| Array<{ id: string; name: string }>
+											| undefined) || [];
+									const hasItemsSelected = selectedFolders.length > 0 || selectedFiles.length > 0;
+									const isDisabled = requiresFolderSelection && !hasItemsSelected;
 
-										return (
-											<PeriodicSyncConfig
-												enabled={periodicEnabled}
-												frequencyMinutes={frequencyMinutes}
-												onEnabledChange={onPeriodicEnabledChange}
-												onFrequencyChange={onFrequencyChange}
-												disabled={isDisabled}
-												disabledMessage={
-													isDisabled
-														? "Select at least one folder or file above to enable periodic sync"
-														: undefined
-												}
-											/>
-										);
-									})()}
+									return (
+										<PeriodicSyncConfig
+											enabled={periodicEnabled}
+											frequencyMinutes={frequencyMinutes}
+											onEnabledChange={onPeriodicEnabledChange}
+											onFrequencyChange={onFrequencyChange}
+											disabled={isDisabled}
+											disabledMessage={
+												isDisabled
+													? "Select at least one folder or file above to enable periodic sync"
+													: undefined
+											}
+										/>
+									);
+								})()}
 							</>
 						)}
 
diff --git a/surfsense_web/components/assistant-ui/document-upload-popup.tsx b/surfsense_web/components/assistant-ui/document-upload-popup.tsx
index 78600be47..4f06588c1 100644
--- a/surfsense_web/components/assistant-ui/document-upload-popup.tsx
+++ b/surfsense_web/components/assistant-ui/document-upload-popup.tsx
@@ -143,7 +143,10 @@ const DocumentUploadPopupContent: FC<{
 
 					<div className="px-4 sm:px-6 pb-4 sm:pb-6">
 						{!isLoading && !hasDocumentSummaryLLM ? (
-							<Alert variant="destructive" className="mb-4 bg-muted/50 rounded-xl border-destructive/30">
+							<Alert
+								variant="destructive"
+								className="mb-4 bg-muted/50 rounded-xl border-destructive/30"
+							>
 								<AlertTriangle className="h-4 w-4" />
 								<AlertTitle>LLM Configuration Required</AlertTitle>
 								<AlertDescription className="mt-2">
diff --git a/surfsense_web/components/assistant-ui/inline-citation.tsx b/surfsense_web/components/assistant-ui/inline-citation.tsx
index 42144f1d6..0c99090e6 100644
--- a/surfsense_web/components/assistant-ui/inline-citation.tsx
+++ b/surfsense_web/components/assistant-ui/inline-citation.tsx
@@ -32,7 +32,8 @@ export const InlineCitation: FC<InlineCitationProps> = ({ chunkId, isDocsChunk =
 			<button
 				type="button"
 				onClick={() => setIsOpen(true)}
-				className="ml-0.5 inline-flex h-5 min-w-5 cursor-pointer items-center justify-center rounded-md bg-muted/60 px-1.5 text-[11px] font-medium text-muted-foreground align-baseline shadow-sm transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none"				title={`View source chunk #${chunkId}`}
+				className="ml-0.5 inline-flex h-5 min-w-5 cursor-pointer items-center justify-center rounded-md bg-muted/60 px-1.5 text-[11px] font-medium text-muted-foreground align-baseline shadow-sm transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-ring focus-visible:ring-2 focus-visible:outline-none"
+				title={`View source chunk #${chunkId}`}
 			>
 				{chunkId}
 			</button>
diff --git a/surfsense_web/components/documents/DocumentNode.tsx b/surfsense_web/components/documents/DocumentNode.tsx
index 31d1bc7ca..919f904d4 100644
--- a/surfsense_web/components/documents/DocumentNode.tsx
+++ b/surfsense_web/components/documents/DocumentNode.tsx
@@ -39,8 +39,8 @@ import { Spinner } from "@/components/ui/spinner";
 import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip";
 import type { DocumentTypeEnum } from "@/contracts/types/document.types";
 import { cn } from "@/lib/utils";
-import { isVersionableType } from "./version-history";
 import { DND_TYPES } from "./FolderNode";
+import { isVersionableType } from "./version-history";
 
 const EDITABLE_DOCUMENT_TYPES = new Set(["FILE", "NOTE"]);
 
@@ -199,7 +199,10 @@ export const DocumentNode = React.memo(function DocumentNode({
 
 					<span className="flex-1 min-w-0 truncate">{doc.title}</span>
 
-					{getDocumentTypeIcon(doc.document_type as DocumentTypeEnum, "h-3.5 w-3.5 text-muted-foreground") && (
+					{getDocumentTypeIcon(
+						doc.document_type as DocumentTypeEnum,
+						"h-3.5 w-3.5 text-muted-foreground"
+					) && (
 						<span className="shrink-0">
 							{getDocumentTypeIcon(
 								doc.document_type as DocumentTypeEnum,
@@ -251,10 +254,7 @@ export const DocumentNode = React.memo(function DocumentNode({
 								</DropdownMenuSub>
 							)}
 							{onVersionHistory && isVersionableType(doc.document_type) && (
-								<DropdownMenuItem
-									disabled={isProcessing}
-									onClick={() => onVersionHistory(doc)}
-								>
+								<DropdownMenuItem disabled={isProcessing} onClick={() => onVersionHistory(doc)}>
 									<History className="mr-2 h-4 w-4" />
 									Versions
 								</DropdownMenuItem>
@@ -300,10 +300,7 @@ export const DocumentNode = React.memo(function DocumentNode({
 						</ContextMenuSub>
 					)}
 					{onVersionHistory && isVersionableType(doc.document_type) && (
-						<ContextMenuItem
-							disabled={isProcessing}
-							onClick={() => onVersionHistory(doc)}
-						>
+						<ContextMenuItem disabled={isProcessing} onClick={() => onVersionHistory(doc)}>
 							<History className="mr-2 h-4 w-4" />
 							Versions
 						</ContextMenuItem>
diff --git a/surfsense_web/components/documents/FolderNode.tsx b/surfsense_web/components/documents/FolderNode.tsx
index 909f965f9..88cc76c69 100644
--- a/surfsense_web/components/documents/FolderNode.tsx
+++ b/surfsense_web/components/documents/FolderNode.tsx
@@ -256,15 +256,15 @@ export const FolderNode = React.memo(function FolderNode({
 						isOver && !canDrop && "cursor-not-allowed"
 					)}
 					style={{ paddingLeft: `${depth * 16 + 4}px` }}
-				onClick={() => {
-					onToggleExpand(folder.id);
-				}}
-				onKeyDown={(e) => {
-					if (e.key === "Enter" || e.key === " ") {
-						e.preventDefault();
+					onClick={() => {
 						onToggleExpand(folder.id);
-					}
-				}}
+					}}
+					onKeyDown={(e) => {
+						if (e.key === "Enter" || e.key === " ") {
+							e.preventDefault();
+							onToggleExpand(folder.id);
+						}
+					}}
 					onDoubleClick={(e) => {
 						e.stopPropagation();
 						startRename();
@@ -306,7 +306,11 @@ export const FolderNode = React.memo(function FolderNode({
 					) : (
 						<Checkbox
 							checked={
-								selectionState === "all" ? true : selectionState === "some" ? "indeterminate" : false
+								selectionState === "all"
+									? true
+									: selectionState === "some"
+										? "indeterminate"
+										: false
 							}
 							onCheckedChange={handleCheckChange}
 							onClick={(e) => e.stopPropagation()}
@@ -350,107 +354,107 @@ export const FolderNode = React.memo(function FolderNode({
 									<MoreHorizontal className="h-3.5 w-3.5" />
 								</Button>
 							</DropdownMenuTrigger>
-						<DropdownMenuContent align="end" className="w-40">
-							{isWatched && onRescan && (
+							<DropdownMenuContent align="end" className="w-40">
+								{isWatched && onRescan && (
+									<DropdownMenuItem
+										onClick={(e) => {
+											e.stopPropagation();
+											onRescan(folder);
+										}}
+									>
+										<RefreshCw className="mr-2 h-4 w-4" />
+										Re-scan
+									</DropdownMenuItem>
+								)}
+								{isWatched && onStopWatching && (
+									<DropdownMenuItem
+										onClick={(e) => {
+											e.stopPropagation();
+											onStopWatching(folder);
+										}}
+									>
+										<EyeOff className="mr-2 h-4 w-4" />
+										Stop watching
+									</DropdownMenuItem>
+								)}
 								<DropdownMenuItem
 									onClick={(e) => {
 										e.stopPropagation();
-										onRescan(folder);
+										onCreateSubfolder(folder.id);
 									}}
 								>
-									<RefreshCw className="mr-2 h-4 w-4" />
-									Re-scan
+									<FolderPlus className="mr-2 h-4 w-4" />
+									New subfolder
 								</DropdownMenuItem>
-							)}
-							{isWatched && onStopWatching && (
 								<DropdownMenuItem
 									onClick={(e) => {
 										e.stopPropagation();
-										onStopWatching(folder);
+										startRename();
 									}}
 								>
-									<EyeOff className="mr-2 h-4 w-4" />
-									Stop watching
+									<PenLine className="mr-2 h-4 w-4" />
+									Rename
 								</DropdownMenuItem>
-							)}
-							<DropdownMenuItem
-								onClick={(e) => {
-									e.stopPropagation();
-									onCreateSubfolder(folder.id);
-								}}
-							>
-								<FolderPlus className="mr-2 h-4 w-4" />
-								New subfolder
-							</DropdownMenuItem>
-							<DropdownMenuItem
-								onClick={(e) => {
-									e.stopPropagation();
-									startRename();
-								}}
-							>
-								<PenLine className="mr-2 h-4 w-4" />
-								Rename
-							</DropdownMenuItem>
-							<DropdownMenuItem
-								onClick={(e) => {
-									e.stopPropagation();
-									onMove(folder);
-								}}
-							>
-								<Move className="mr-2 h-4 w-4" />
-								Move to...
-							</DropdownMenuItem>
-							<DropdownMenuItem
-								className="text-destructive focus:text-destructive"
-								onClick={(e) => {
-									e.stopPropagation();
-									onDelete(folder);
-								}}
-							>
-								<Trash2 className="mr-2 h-4 w-4" />
-								Delete
-							</DropdownMenuItem>
-						</DropdownMenuContent>
+								<DropdownMenuItem
+									onClick={(e) => {
+										e.stopPropagation();
+										onMove(folder);
+									}}
+								>
+									<Move className="mr-2 h-4 w-4" />
+									Move to...
+								</DropdownMenuItem>
+								<DropdownMenuItem
+									className="text-destructive focus:text-destructive"
+									onClick={(e) => {
+										e.stopPropagation();
+										onDelete(folder);
+									}}
+								>
+									<Trash2 className="mr-2 h-4 w-4" />
+									Delete
+								</DropdownMenuItem>
+							</DropdownMenuContent>
 						</DropdownMenu>
 					)}
 				</div>
 			</ContextMenuTrigger>
 
-		{!isRenaming && contextMenuOpen && (
-			<ContextMenuContent className="w-40">
-				{isWatched && onRescan && (
-					<ContextMenuItem onClick={() => onRescan(folder)}>
-						<RefreshCw className="mr-2 h-4 w-4" />
-						Re-scan
+			{!isRenaming && contextMenuOpen && (
+				<ContextMenuContent className="w-40">
+					{isWatched && onRescan && (
+						<ContextMenuItem onClick={() => onRescan(folder)}>
+							<RefreshCw className="mr-2 h-4 w-4" />
+							Re-scan
+						</ContextMenuItem>
+					)}
+					{isWatched && onStopWatching && (
+						<ContextMenuItem onClick={() => onStopWatching(folder)}>
+							<EyeOff className="mr-2 h-4 w-4" />
+							Stop watching
+						</ContextMenuItem>
+					)}
+					<ContextMenuItem onClick={() => onCreateSubfolder(folder.id)}>
+						<FolderPlus className="mr-2 h-4 w-4" />
+						New subfolder
 					</ContextMenuItem>
-				)}
-				{isWatched && onStopWatching && (
-					<ContextMenuItem onClick={() => onStopWatching(folder)}>
-						<EyeOff className="mr-2 h-4 w-4" />
-						Stop watching
+					<ContextMenuItem onClick={() => startRename()}>
+						<PenLine className="mr-2 h-4 w-4" />
+						Rename
 					</ContextMenuItem>
-				)}
-				<ContextMenuItem onClick={() => onCreateSubfolder(folder.id)}>
-					<FolderPlus className="mr-2 h-4 w-4" />
-					New subfolder
-				</ContextMenuItem>
-				<ContextMenuItem onClick={() => startRename()}>
-					<PenLine className="mr-2 h-4 w-4" />
-					Rename
-				</ContextMenuItem>
-				<ContextMenuItem onClick={() => onMove(folder)}>
-					<Move className="mr-2 h-4 w-4" />
-					Move to...
-				</ContextMenuItem>
-				<ContextMenuItem
-					className="text-destructive focus:text-destructive"
-					onClick={() => onDelete(folder)}
-				>
-					<Trash2 className="mr-2 h-4 w-4" />
-					Delete
-				</ContextMenuItem>
-			</ContextMenuContent>
-		)}
+					<ContextMenuItem onClick={() => onMove(folder)}>
+						<Move className="mr-2 h-4 w-4" />
+						Move to...
+					</ContextMenuItem>
+					<ContextMenuItem
+						className="text-destructive focus:text-destructive"
+						onClick={() => onDelete(folder)}
+					>
+						<Trash2 className="mr-2 h-4 w-4" />
+						Delete
+					</ContextMenuItem>
+				</ContextMenuContent>
+			)}
 		</ContextMenu>
 	);
 });
diff --git a/surfsense_web/components/documents/FolderTreeView.tsx b/surfsense_web/components/documents/FolderTreeView.tsx
index 3aa8ce9d8..1df007c0b 100644
--- a/surfsense_web/components/documents/FolderTreeView.tsx
+++ b/surfsense_web/components/documents/FolderTreeView.tsx
@@ -242,10 +242,10 @@ export function FolderTreeView({
 					siblingPositions={siblingPositions}
 					contextMenuOpen={openContextMenuId === `folder-${f.id}`}
 					onContextMenuOpenChange={(open) => setOpenContextMenuId(open ? `folder-${f.id}` : null)}
-				isWatched={watchedFolderIds?.has(f.id)}
-				onRescan={onRescanFolder}
-				onStopWatching={onStopWatchingFolder}
-			/>
+					isWatched={watchedFolderIds?.has(f.id)}
+					onRescan={onRescanFolder}
+					onStopWatching={onStopWatchingFolder}
+				/>
 			);
 
 			if (isExpanded) {
diff --git a/surfsense_web/components/documents/version-history.tsx b/surfsense_web/components/documents/version-history.tsx
index 7aba92b47..27343dc6a 100644
--- a/surfsense_web/components/documents/version-history.tsx
+++ b/surfsense_web/components/documents/version-history.tsx
@@ -1,19 +1,14 @@
 "use client";
 
-import { useCallback, useEffect, useState } from "react";
 import { Check, ChevronRight, Clock, Copy, RotateCcw } from "lucide-react";
+import { useCallback, useEffect, useState } from "react";
+import { toast } from "sonner";
 import { Button } from "@/components/ui/button";
-import {
-	Dialog,
-	DialogContent,
-	DialogTitle,
-	DialogTrigger,
-} from "@/components/ui/dialog";
+import { Dialog, DialogContent, DialogTitle, DialogTrigger } from "@/components/ui/dialog";
 import { Separator } from "@/components/ui/separator";
 import { Spinner } from "@/components/ui/spinner";
-import { cn } from "@/lib/utils";
 import { documentsApiService } from "@/lib/apis/documents-api.service";
-import { toast } from "sonner";
+import { cn } from "@/lib/utils";
 
 interface DocumentVersionSummary {
 	version_number: number;
@@ -123,10 +118,9 @@ function VersionHistoryPanel({ documentId }: { documentId: number }) {
 		setSelectedVersion(versionNumber);
 		setContentLoading(true);
 		try {
-			const data = (await documentsApiService.getDocumentVersion(
-				documentId,
-				versionNumber
-			)) as { source_markdown: string };
+			const data = (await documentsApiService.getDocumentVersion(documentId, versionNumber)) as {
+				source_markdown: string;
+			};
 			setVersionContent(data.source_markdown || "");
 		} catch {
 			toast.error("Failed to load version content");
@@ -196,13 +190,11 @@ function VersionHistoryPanel({ documentId }: { documentId: number }) {
 							>
 								<div className="flex-1 min-w-0 space-y-0.5">
 									<p className="text-sm font-medium truncate">
-										{v.created_at ? formatRelativeTime(v.created_at) : `Version ${v.version_number}`}
+										{v.created_at
+											? formatRelativeTime(v.created_at)
+											: `Version ${v.version_number}`}
 									</p>
-									{v.title && (
-										<p className="text-xs text-muted-foreground truncate">
-											{v.title}
-										</p>
-									)}
+									{v.title && <p className="text-xs text-muted-foreground truncate">{v.title}</p>}
 								</div>
 								<ChevronRight className="h-3.5 w-3.5 shrink-0 opacity-50" />
 							</button>
@@ -227,11 +219,7 @@ function VersionHistoryPanel({ documentId }: { documentId: number }) {
 									onClick={handleCopy}
 									disabled={contentLoading || copied}
 								>
-									{copied ? (
-										<Check className="h-3 w-3" />
-									) : (
-										<Copy className="h-3 w-3" />
-									)}
+									{copied ? <Check className="h-3 w-3" /> : <Copy className="h-3 w-3" />}
 									{copied ? "Copied" : "Copy"}
 								</Button>
 								<Button
@@ -241,11 +229,7 @@ function VersionHistoryPanel({ documentId }: { documentId: number }) {
 									disabled={restoring || contentLoading}
 									onClick={() => handleRestore(selectedVersion)}
 								>
-									{restoring ? (
-										<Spinner size="xs" />
-									) : (
-										<RotateCcw className="h-3 w-3" />
-									)}
+									{restoring ? <Spinner size="xs" /> : <RotateCcw className="h-3 w-3" />}
 									Restore
 								</Button>
 							</div>
diff --git a/surfsense_web/components/editor-panel/editor-panel.tsx b/surfsense_web/components/editor-panel/editor-panel.tsx
index 59af0ee8d..05bcd2dc0 100644
--- a/surfsense_web/components/editor-panel/editor-panel.tsx
+++ b/surfsense_web/components/editor-panel/editor-panel.tsx
@@ -54,7 +54,6 @@ function EditorPanelSkeleton() {
 	);
 }
 
-
 export function EditorPanelContent({
 	documentId,
 	searchSpaceId,
@@ -194,24 +193,24 @@ export function EditorPanelContent({
 	return (
 		<>
 			<div className="flex items-center justify-between px-4 py-2 shrink-0 border-b">
-			<div className="flex-1 min-w-0">
-				<h2 className="text-sm font-semibold truncate">{displayTitle}</h2>
-				{isEditableType && editedMarkdown !== null && (
-					<p className="text-[10px] text-muted-foreground">Unsaved changes</p>
-				)}
+				<div className="flex-1 min-w-0">
+					<h2 className="text-sm font-semibold truncate">{displayTitle}</h2>
+					{isEditableType && editedMarkdown !== null && (
+						<p className="text-[10px] text-muted-foreground">Unsaved changes</p>
+					)}
+				</div>
+				<div className="flex items-center gap-1 shrink-0">
+					{editorDoc?.document_type && (
+						<VersionHistoryButton documentId={documentId} documentType={editorDoc.document_type} />
+					)}
+					{onClose && (
+						<Button variant="ghost" size="icon" onClick={onClose} className="size-7 shrink-0">
+							<XIcon className="size-4" />
+							<span className="sr-only">Close editor panel</span>
+						</Button>
+					)}
+				</div>
 			</div>
-			<div className="flex items-center gap-1 shrink-0">
-				{editorDoc?.document_type && (
-					<VersionHistoryButton documentId={documentId} documentType={editorDoc.document_type} />
-				)}
-				{onClose && (
-					<Button variant="ghost" size="icon" onClick={onClose} className="size-7 shrink-0">
-						<XIcon className="size-4" />
-						<span className="sr-only">Close editor panel</span>
-					</Button>
-				)}
-			</div>
-		</div>
 
 			<div className="flex-1 overflow-hidden">
 				{isLoading ? (
@@ -233,7 +232,9 @@ export function EditorPanelContent({
 									? "Document is processing"
 									: "Document unavailable"}
 							</p>
-							<p className="text-sm text-muted-foreground">{error || "An unknown error occurred"}</p>
+							<p className="text-sm text-muted-foreground">
+								{error || "An unknown error occurred"}
+							</p>
 						</div>
 					</div>
 				) : isLargeDocument ? (
diff --git a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
index c10c5dc82..aa409e179 100644
--- a/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/DocumentsSidebar.tsx
@@ -121,9 +121,7 @@ export function DocumentsSidebar({
 					}
 					const recovered = await api!.getWatchedFolders();
 					const ids = new Set(
-						recovered
-							.filter((f) => f.rootFolderId != null)
-							.map((f) => f.rootFolderId as number)
+						recovered.filter((f) => f.rootFolderId != null).map((f) => f.rootFolderId as number)
 					);
 					setWatchedFolderIds(ids);
 					return;
@@ -133,9 +131,7 @@ export function DocumentsSidebar({
 			}
 
 			const ids = new Set(
-				folders
-					.filter((f) => f.rootFolderId != null)
-					.map((f) => f.rootFolderId as number)
+				folders.filter((f) => f.rootFolderId != null).map((f) => f.rootFolderId as number)
 			);
 			setWatchedFolderIds(ids);
 		}
@@ -305,28 +301,25 @@ export function DocumentsSidebar({
 		[searchSpaceId]
 	);
 
-	const handleStopWatching = useCallback(
-		async (folder: FolderDisplay) => {
-			const api = window.electronAPI;
-			if (!api) return;
+	const handleStopWatching = useCallback(async (folder: FolderDisplay) => {
+		const api = window.electronAPI;
+		if (!api) return;
 
-			const watchedFolders = await api.getWatchedFolders();
-			const matched = watchedFolders.find((wf) => wf.rootFolderId === folder.id);
-			if (!matched) {
-				toast.error("This folder is not being watched");
-				return;
-			}
+		const watchedFolders = await api.getWatchedFolders();
+		const matched = watchedFolders.find((wf) => wf.rootFolderId === folder.id);
+		if (!matched) {
+			toast.error("This folder is not being watched");
+			return;
+		}
 
-			await api.removeWatchedFolder(matched.path);
-			try {
-				await foldersApiService.stopWatching(folder.id);
-			} catch (err) {
-				console.error("[DocumentsSidebar] Failed to clear watched metadata:", err);
-			}
-			toast.success(`Stopped watching: ${matched.name}`);
-		},
-		[]
-	);
+		await api.removeWatchedFolder(matched.path);
+		try {
+			await foldersApiService.stopWatching(folder.id);
+		} catch (err) {
+			console.error("[DocumentsSidebar] Failed to clear watched metadata:", err);
+		}
+		toast.success(`Stopped watching: ${matched.name}`);
+	}, []);
 
 	const handleRenameFolder = useCallback(async (folder: FolderDisplay, newName: string) => {
 		try {
@@ -755,81 +748,83 @@ export function DocumentsSidebar({
 
 			<div className="flex-1 min-h-0 overflow-x-hidden pt-0 flex flex-col">
 				<div className="px-4 pb-2">
-			<DocumentsFilters
-				typeCounts={typeCounts}
-				onSearch={setSearch}
-				searchValue={search}
-				onToggleType={onToggleType}
-				activeTypes={activeTypes}
-				onCreateFolder={() => handleCreateFolder(null)}
-			/>
+					<DocumentsFilters
+						typeCounts={typeCounts}
+						onSearch={setSearch}
+						searchValue={search}
+						onToggleType={onToggleType}
+						activeTypes={activeTypes}
+						onCreateFolder={() => handleCreateFolder(null)}
+					/>
 				</div>
 
-			<div className="relative flex-1 min-h-0 overflow-auto">
-				{deletableSelectedIds.length > 0 && (
-					<div className="absolute inset-x-0 top-0 z-10 flex items-center justify-center px-4 py-1.5 animate-in fade-in duration-150 pointer-events-none">
-						<button
-							type="button"
-							onClick={() => setBulkDeleteConfirmOpen(true)}
-							className="pointer-events-auto flex items-center gap-1.5 px-3 py-1 rounded-md bg-destructive text-destructive-foreground shadow-lg text-xs font-medium hover:bg-destructive/90 transition-colors"
-						>
-							<Trash2 size={12} />
-							Delete {deletableSelectedIds.length}{" "}
-							{deletableSelectedIds.length === 1 ? "item" : "items"}
-						</button>
-					</div>
-				)}
+				<div className="relative flex-1 min-h-0 overflow-auto">
+					{deletableSelectedIds.length > 0 && (
+						<div className="absolute inset-x-0 top-0 z-10 flex items-center justify-center px-4 py-1.5 animate-in fade-in duration-150 pointer-events-none">
+							<button
+								type="button"
+								onClick={() => setBulkDeleteConfirmOpen(true)}
+								className="pointer-events-auto flex items-center gap-1.5 px-3 py-1 rounded-md bg-destructive text-destructive-foreground shadow-lg text-xs font-medium hover:bg-destructive/90 transition-colors"
+							>
+								<Trash2 size={12} />
+								Delete {deletableSelectedIds.length}{" "}
+								{deletableSelectedIds.length === 1 ? "item" : "items"}
+							</button>
+						</div>
+					)}
 
-			<FolderTreeView
-				folders={treeFolders}
-				documents={searchFilteredDocuments}
-				expandedIds={expandedIds}
-				onToggleExpand={toggleFolderExpand}
-				mentionedDocIds={mentionedDocIds}
-				onToggleChatMention={handleToggleChatMention}
-				onToggleFolderSelect={handleToggleFolderSelect}
-				onRenameFolder={handleRenameFolder}
-				onDeleteFolder={handleDeleteFolder}
-				onMoveFolder={handleMoveFolder}
-				onCreateFolder={handleCreateFolder}
-				searchQuery={debouncedSearch.trim() || undefined}
-				onPreviewDocument={(doc) => {
-					openEditorPanel({
-						documentId: doc.id,
-						searchSpaceId,
-						title: doc.title,
-					});
-				}}
-				onEditDocument={(doc) => {
-					openEditorPanel({
-						documentId: doc.id,
-						searchSpaceId,
-						title: doc.title,
-					});
-				}}
-				onDeleteDocument={(doc) => handleDeleteDocument(doc.id)}
-				onMoveDocument={handleMoveDocument}
-				onExportDocument={handleExportDocument}
-				onVersionHistory={(doc) => setVersionDocId(doc.id)}
-				activeTypes={activeTypes}
-				onDropIntoFolder={handleDropIntoFolder}
-				onReorderFolder={handleReorderFolder}
-				watchedFolderIds={watchedFolderIds}
-				onRescanFolder={handleRescanFolder}
-			onStopWatchingFolder={handleStopWatching}
-		/>
+					<FolderTreeView
+						folders={treeFolders}
+						documents={searchFilteredDocuments}
+						expandedIds={expandedIds}
+						onToggleExpand={toggleFolderExpand}
+						mentionedDocIds={mentionedDocIds}
+						onToggleChatMention={handleToggleChatMention}
+						onToggleFolderSelect={handleToggleFolderSelect}
+						onRenameFolder={handleRenameFolder}
+						onDeleteFolder={handleDeleteFolder}
+						onMoveFolder={handleMoveFolder}
+						onCreateFolder={handleCreateFolder}
+						searchQuery={debouncedSearch.trim() || undefined}
+						onPreviewDocument={(doc) => {
+							openEditorPanel({
+								documentId: doc.id,
+								searchSpaceId,
+								title: doc.title,
+							});
+						}}
+						onEditDocument={(doc) => {
+							openEditorPanel({
+								documentId: doc.id,
+								searchSpaceId,
+								title: doc.title,
+							});
+						}}
+						onDeleteDocument={(doc) => handleDeleteDocument(doc.id)}
+						onMoveDocument={handleMoveDocument}
+						onExportDocument={handleExportDocument}
+						onVersionHistory={(doc) => setVersionDocId(doc.id)}
+						activeTypes={activeTypes}
+						onDropIntoFolder={handleDropIntoFolder}
+						onReorderFolder={handleReorderFolder}
+						watchedFolderIds={watchedFolderIds}
+						onRescanFolder={handleRescanFolder}
+						onStopWatchingFolder={handleStopWatching}
+					/>
+				</div>
 			</div>
-		</div>
 
-		{versionDocId !== null && (
-			<VersionHistoryDialog
-				open
-				onOpenChange={(open) => { if (!open) setVersionDocId(null); }}
-				documentId={versionDocId}
-			/>
-		)}
+			{versionDocId !== null && (
+				<VersionHistoryDialog
+					open
+					onOpenChange={(open) => {
+						if (!open) setVersionDocId(null);
+					}}
+					documentId={versionDocId}
+				/>
+			)}
 
-		<FolderPickerDialog
+			<FolderPickerDialog
 				open={folderPickerOpen}
 				onOpenChange={setFolderPickerOpen}
 				folders={treeFolders}
diff --git a/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx b/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx
index 2e7269c57..c781bd731 100644
--- a/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx
+++ b/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx
@@ -185,9 +185,7 @@ export function DocumentTabContent({ documentId, searchSpaceId, title }: Documen
 					<p className="font-semibold text-foreground text-lg">
 						{isProcessing ? "Document is processing" : "Document unavailable"}
 					</p>
-					<p className="text-sm text-muted-foreground">
-						{error || "An unknown error occurred"}
-					</p>
+					<p className="text-sm text-muted-foreground">{error || "An unknown error occurred"}</p>
 				</div>
 				{!isProcessing && (
 					<Button
diff --git a/surfsense_web/components/new-chat/source-detail-panel.tsx b/surfsense_web/components/new-chat/source-detail-panel.tsx
index 8593f96db..ed6c7e4ac 100644
--- a/surfsense_web/components/new-chat/source-detail-panel.tsx
+++ b/surfsense_web/components/new-chat/source-detail-panel.tsx
@@ -480,9 +480,7 @@ export function SourceDetailPanel({
 										<FileQuestionMark className="h-10 w-10 text-muted-foreground" />
 									</div>
 									<div>
-										<p className="font-semibold text-foreground text-lg">
-											Document unavailable
-										</p>
+										<p className="font-semibold text-foreground text-lg">Document unavailable</p>
 										<p className="text-sm text-muted-foreground mt-2 max-w-md">
 											{documentByChunkFetchingError.message ||
 												"An unexpected error occurred. Please try again."}
diff --git a/surfsense_web/components/settings/llm-role-manager.tsx b/surfsense_web/components/settings/llm-role-manager.tsx
index d1651b7f0..718503318 100644
--- a/surfsense_web/components/settings/llm-role-manager.tsx
+++ b/surfsense_web/components/settings/llm-role-manager.tsx
@@ -134,24 +134,27 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 		preferences?.image_generation_config_id,
 	]);
 
-	const handleRoleAssignment = useCallback(async (prefKey: string, configId: string) => {
-		const value = configId === "unassigned" ? "" : parseInt(configId);
+	const handleRoleAssignment = useCallback(
+		async (prefKey: string, configId: string) => {
+			const value = configId === "unassigned" ? "" : parseInt(configId);
 
-		setAssignments((prev) => ({ ...prev, [prefKey]: value }));
-		setSavingRole(prefKey);
-		savingRef.current = true;
+			setAssignments((prev) => ({ ...prev, [prefKey]: value }));
+			setSavingRole(prefKey);
+			savingRef.current = true;
 
-		try {
-			await updatePreferences({
-				search_space_id: searchSpaceId,
-				data: { [prefKey]: value || undefined },
-			});
-			toast.success("Role assignment updated");
-		} finally {
-			setSavingRole(null);
-			savingRef.current = false;
-		}
-	}, [updatePreferences, searchSpaceId]);
+			try {
+				await updatePreferences({
+					search_space_id: searchSpaceId,
+					data: { [prefKey]: value || undefined },
+				});
+				toast.success("Role assignment updated");
+			} finally {
+				setSavingRole(null);
+				savingRef.current = false;
+			}
+		},
+		[updatePreferences, searchSpaceId]
+	);
 
 	// Combine global and custom LLM configs
 	const allLLMConfigs = [
@@ -199,10 +202,7 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 					Refresh
 				</Button>
 				{isAssignmentComplete && !isLoading && !hasError && (
-					<Badge
-						variant="outline"
-						className="text-xs gap-1.5 text-muted-foreground"
-					>
+					<Badge variant="outline" className="text-xs gap-1.5 text-muted-foreground">
 						<CircleCheck className="h-3 w-3" />
 						All roles assigned
 					</Badge>
@@ -483,7 +483,6 @@ export function LLMRoleManager({ searchSpaceId }: LLMRoleManagerProps) {
 					})}
 				</div>
 			)}
-
 		</div>
 	);
 }
diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index 9733bd2e6..f1162f57c 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -128,7 +128,8 @@ const MAX_TOTAL_SIZE_BYTES = MAX_TOTAL_SIZE_MB * 1024 * 1024;
 const MAX_FILE_SIZE_MB = 500;
 const MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024;
 
-const toggleRowClass = "flex items-center justify-between rounded-lg bg-slate-400/5 dark:bg-white/5 p-3";
+const toggleRowClass =
+	"flex items-center justify-between rounded-lg bg-slate-400/5 dark:bg-white/5 p-3";
 
 export function DocumentUploadTab({
 	searchSpaceId,
@@ -326,7 +327,14 @@ export function DocumentUploadTab({
 				await api.addWatchedFolder({
 					path: selectedFolder.path,
 					name: selectedFolder.name,
-					excludePatterns: [".git", "node_modules", "__pycache__", ".DS_Store", ".obsidian", ".trash"],
+					excludePatterns: [
+						".git",
+						"node_modules",
+						"__pycache__",
+						".DS_Store",
+						".obsidian",
+						".trash",
+					],
 					fileExtensions: null,
 					rootFolderId,
 					searchSpaceId: Number(searchSpaceId),
@@ -393,12 +401,20 @@ export function DocumentUploadTab({
 			return (
 				<DropdownMenu>
 					<DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
-						<Button variant="ghost" size="sm" className={`text-xs gap-1 bg-neutral-700/50 hover:bg-neutral-600/50 ${sizeClass} ${widthClass}`}>
+						<Button
+							variant="ghost"
+							size="sm"
+							className={`text-xs gap-1 bg-neutral-700/50 hover:bg-neutral-600/50 ${sizeClass} ${widthClass}`}
+						>
 							Browse
 							<ChevronDown className="h-3 w-3 opacity-60" />
 						</Button>
 					</DropdownMenuTrigger>
-					<DropdownMenuContent align="center" className="dark:bg-neutral-800" onClick={(e) => e.stopPropagation()}>
+					<DropdownMenuContent
+						align="center"
+						className="dark:bg-neutral-800"
+						onClick={(e) => e.stopPropagation()}
+					>
 						<DropdownMenuItem onClick={handleBrowseFiles}>
 							<FileIcon className="h-4 w-4 mr-2" />
 							Files
@@ -415,7 +431,11 @@ export function DocumentUploadTab({
 		return (
 			<DropdownMenu>
 				<DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
-					<Button variant="secondary" size="sm" className={`text-xs gap-1 ${sizeClass} ${widthClass}`}>
+					<Button
+						variant="secondary"
+						size="sm"
+						className={`text-xs gap-1 ${sizeClass} ${widthClass}`}
+					>
 						Browse
 						<ChevronDown className="h-3 w-3 opacity-60" />
 					</Button>
@@ -457,21 +477,19 @@ export function DocumentUploadTab({
 			{/* MOBILE DROP ZONE */}
 			<div className="sm:hidden">
 				{hasContent ? (
-					!selectedFolder && !isFileCountLimitReached && (
-						isElectron ? (
-							<div className="w-full">
-								{renderBrowseButton({ compact: true, fullWidth: true })}
-							</div>
-						) : (
-							<button
-								type="button"
-								className="w-full text-xs h-8 flex items-center justify-center gap-1.5 rounded-md border border-dashed border-muted-foreground/30 text-muted-foreground hover:text-foreground hover:border-foreground/50 transition-colors"
-								onClick={() => fileInputRef.current?.click()}
-							>
-								Add more files
-							</button>
-						)
-					)
+					!selectedFolder &&
+					!isFileCountLimitReached &&
+					(isElectron ? (
+						<div className="w-full">{renderBrowseButton({ compact: true, fullWidth: true })}</div>
+					) : (
+						<button
+							type="button"
+							className="w-full text-xs h-8 flex items-center justify-center gap-1.5 rounded-md border border-dashed border-muted-foreground/30 text-muted-foreground hover:text-foreground hover:border-foreground/50 transition-colors"
+							onClick={() => fileInputRef.current?.click()}
+						>
+							Add more files
+						</button>
+					))
 				) : (
 					<div
 						className="flex flex-col items-center gap-4 py-12 px-4 cursor-pointer"
@@ -487,7 +505,9 @@ export function DocumentUploadTab({
 							<p className="text-sm text-muted-foreground inline-flex items-center flex-wrap justify-center">
 								<span>{t("file_size_limit")}</span>
 								<Dot className="h-4 w-4 shrink-0" />
-								<span>{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}</span>
+								<span>
+									{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}
+								</span>
 							</p>
 						</div>
 						<div className="w-full mt-1" onClick={(e) => e.stopPropagation()}>
@@ -538,7 +558,9 @@ export function DocumentUploadTab({
 						<p className="text-xs text-muted-foreground text-center inline-flex items-center flex-wrap justify-center">
 							<span>{t("file_size_limit")}</span>
 							<Dot className="h-4 w-4 shrink-0" />
-							<span>{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}</span>
+							<span>
+								{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}
+							</span>
 						</p>
 						<div className="mt-1">{renderBrowseButton()}</div>
 					</div>
@@ -569,9 +591,7 @@ export function DocumentUploadTab({
 						<div className="flex items-center justify-between p-3">
 							<div className="space-y-0.5">
 								<p className="font-medium text-sm">Watch folder</p>
-								<p className="text-xs text-muted-foreground">
-									Auto-sync when files change
-								</p>
+								<p className="text-xs text-muted-foreground">Auto-sync when files change</p>
 							</div>
 							<Switch
 								id="watch-folder-toggle"
@@ -612,7 +632,8 @@ export function DocumentUploadTab({
 				<div className="rounded-lg border border-border p-3 space-y-2">
 					<div className="flex items-center justify-between">
 						<p className="text-sm font-medium">
-							{t("selected_files", { count: files.length })} &middot; {formatFileSize(totalFileSize)}
+							{t("selected_files", { count: files.length })} &middot;{" "}
+							{formatFileSize(totalFileSize)}
 						</p>
 						<Button
 							variant="ghost"
diff --git a/surfsense_web/lib/apis/connectors-api.service.ts b/surfsense_web/lib/apis/connectors-api.service.ts
index 7b94b3746..abd16c7a7 100644
--- a/surfsense_web/lib/apis/connectors-api.service.ts
+++ b/surfsense_web/lib/apis/connectors-api.service.ts
@@ -404,7 +404,6 @@ class ConnectorsApiService {
 			listDiscordChannelsResponse
 		);
 	};
-
 }
 
 export type { SlackChannel, DiscordChannel };
diff --git a/surfsense_web/lib/apis/documents-api.service.ts b/surfsense_web/lib/apis/documents-api.service.ts
index f72e1dbcc..5961522ec 100644
--- a/surfsense_web/lib/apis/documents-api.service.ts
+++ b/surfsense_web/lib/apis/documents-api.service.ts
@@ -417,27 +417,47 @@ class DocumentsApiService {
 	};
 
 	getDocumentVersion = async (documentId: number, versionNumber: number) => {
-		return baseApiService.get(
-			`/api/v1/documents/${documentId}/versions/${versionNumber}`
-		);
+		return baseApiService.get(`/api/v1/documents/${documentId}/versions/${versionNumber}`);
 	};
 
 	restoreDocumentVersion = async (documentId: number, versionNumber: number) => {
-		return baseApiService.post(
-			`/api/v1/documents/${documentId}/versions/${versionNumber}/restore`
-		);
+		return baseApiService.post(`/api/v1/documents/${documentId}/versions/${versionNumber}/restore`);
 	};
 
-	folderIndex = async (searchSpaceId: number, body: { folder_path: string; folder_name: string; search_space_id: number; exclude_patterns?: string[]; file_extensions?: string[]; root_folder_id?: number; enable_summary?: boolean }) => {
+	folderIndex = async (
+		searchSpaceId: number,
+		body: {
+			folder_path: string;
+			folder_name: string;
+			search_space_id: number;
+			exclude_patterns?: string[];
+			file_extensions?: string[];
+			root_folder_id?: number;
+			enable_summary?: boolean;
+		}
+	) => {
 		return baseApiService.post(`/api/v1/documents/folder-index`, undefined, { body });
 	};
 
-	folderIndexFiles = async (searchSpaceId: number, body: { folder_path: string; folder_name: string; search_space_id: number; target_file_paths: string[]; root_folder_id?: number | null; enable_summary?: boolean }) => {
+	folderIndexFiles = async (
+		searchSpaceId: number,
+		body: {
+			folder_path: string;
+			folder_name: string;
+			search_space_id: number;
+			target_file_paths: string[];
+			root_folder_id?: number | null;
+			enable_summary?: boolean;
+		}
+	) => {
 		return baseApiService.post(`/api/v1/documents/folder-index-files`, undefined, { body });
 	};
 
 	getWatchedFolders = async (searchSpaceId: number) => {
-		return baseApiService.get(`/api/v1/documents/watched-folders?search_space_id=${searchSpaceId}`, folderListResponse);
+		return baseApiService.get(
+			`/api/v1/documents/watched-folders?search_space_id=${searchSpaceId}`,
+			folderListResponse
+		);
 	};
 
 	/**

From c964b47f99a53cef556342061d42f8c1f4c78a91 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 13:59:33 +0530
Subject: [PATCH 57/70] style: enhance folder selection UI in DocumentUploadTab

---
 surfsense_web/components/sources/DocumentUploadTab.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index f1162f57c..940d1560a 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -570,7 +570,7 @@ export function DocumentUploadTab({
 			{/* FOLDER SELECTED (Electron only — web flattens folder contents into file list) */}
 			{isElectron && selectedFolder && (
 				<div className="rounded-lg border border-border p-3 space-y-2">
-					<div className="flex items-center gap-2">
+					<div className="flex items-center gap-2 py-1.5 px-2 -mx-1 rounded-md hover:bg-slate-400/5 dark:hover:bg-white/5 group">
 						<FolderOpen className="h-4 w-4 text-primary shrink-0" />
 						<div className="min-w-0 flex-1">
 							<p className="text-sm font-medium truncate">{selectedFolder.name}</p>

From 8a8e5fcd76c5dcebb6fbc2142212408553ee7d6d Mon Sep 17 00:00:00 2001
From: SohamBhattacharjee2003
 <125297948+SohamBhattacharjee2003@users.noreply.github.com>
Date: Fri, 3 Apr 2026 14:29:41 +0530
Subject: [PATCH 58/70] fix(hooks): add AbortController to properly cancel
 fetch requests on unmount

---
 package-lock.json                              |  6 ++++++
 .../components/circleback-config.tsx           | 16 ++++++++++++----
 .../components/editor-panel/editor-panel.tsx   | 18 ++++++++----------
 .../layout/ui/tabs/DocumentTabContent.tsx      | 18 ++++++++----------
 4 files changed, 34 insertions(+), 24 deletions(-)
 create mode 100644 package-lock.json

diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 000000000..9703ac09f
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,6 @@
+{
+  "name": "SurfSense",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {}
+}
diff --git a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/circleback-config.tsx b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/circleback-config.tsx
index 99e26c542..268ab0f98 100644
--- a/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/circleback-config.tsx
+++ b/surfsense_web/components/assistant-ui/connector-popup/connector-configs/components/circleback-config.tsx
@@ -34,9 +34,12 @@ export const CirclebackConfig: FC<CirclebackConfigProps> = ({ connector, onNameC
 	const [isLoading, setIsLoading] = useState(true);
 	const [copied, setCopied] = useState(false);
 
+	// Fetch webhook info
 	// Fetch webhook info
 	useEffect(() => {
-		const fetchWebhookInfo = async () => {
+		const controller = new AbortController();
+
+		const doFetch = async () => {
 			if (!connector.search_space_id) return;
 
 			const baseUrl = process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL;
@@ -49,8 +52,11 @@ export const CirclebackConfig: FC<CirclebackConfigProps> = ({ connector, onNameC
 			setIsLoading(true);
 			try {
 				const response = await authenticatedFetch(
-					`${baseUrl}/api/v1/webhooks/circleback/${connector.search_space_id}/info`
+					`${baseUrl}/api/v1/webhooks/circleback/${connector.search_space_id}/info`,
+					{ signal: controller.signal }
 				);
+				if (controller.signal.aborted) return;
+
 				if (response.ok) {
 					const data: unknown = await response.json();
 					// Runtime validation with zod schema
@@ -59,16 +65,18 @@ export const CirclebackConfig: FC<CirclebackConfigProps> = ({ connector, onNameC
 					setWebhookUrl(validatedData.webhook_url);
 				}
 			} catch (error) {
+				if (controller.signal.aborted) return;
 				console.error("Failed to fetch webhook info:", error);
 				// Reset state on error
 				setWebhookInfo(null);
 				setWebhookUrl("");
 			} finally {
-				setIsLoading(false);
+				if (!controller.signal.aborted) setIsLoading(false);
 			}
 		};
 
-		fetchWebhookInfo();
+		doFetch().catch(() => {});
+		return () => controller.abort();
 	}, [connector.search_space_id]);
 
 	const handleNameChange = (value: string) => {
diff --git a/surfsense_web/components/editor-panel/editor-panel.tsx b/surfsense_web/components/editor-panel/editor-panel.tsx
index 3ea36f800..3c204f1bb 100644
--- a/surfsense_web/components/editor-panel/editor-panel.tsx
+++ b/surfsense_web/components/editor-panel/editor-panel.tsx
@@ -70,7 +70,7 @@ export function EditorPanelContent({
 	const [displayTitle, setDisplayTitle] = useState(title || "Untitled");
 
 	useEffect(() => {
-		let cancelled = false;
+		const controller = new AbortController();
 		setIsLoading(true);
 		setError(null);
 		setEditorDoc(null);
@@ -78,7 +78,7 @@ export function EditorPanelContent({
 		initialLoadDone.current = false;
 		changeCountRef.current = 0;
 
-		const fetchContent = async () => {
+		const doFetch = async () => {
 			const token = getBearerToken();
 			if (!token) {
 				redirectToLogin();
@@ -88,10 +88,10 @@ export function EditorPanelContent({
 			try {
 				const response = await authenticatedFetch(
 					`${process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL}/api/v1/search-spaces/${searchSpaceId}/documents/${documentId}/editor-content`,
-					{ method: "GET" }
+					{ method: "GET", signal: controller.signal }
 				);
 
-				if (cancelled) return;
+				if (controller.signal.aborted) return;
 
 				if (!response.ok) {
 					const errorData = await response
@@ -115,18 +115,16 @@ export function EditorPanelContent({
 				setEditorDoc(data);
 				initialLoadDone.current = true;
 			} catch (err) {
-				if (cancelled) return;
+				if (controller.signal.aborted) return;
 				console.error("Error fetching document:", err);
 				setError(err instanceof Error ? err.message : "Failed to fetch document");
 			} finally {
-				if (!cancelled) setIsLoading(false);
+				if (!controller.signal.aborted) setIsLoading(false);
 			}
 		};
 
-		fetchContent();
-		return () => {
-			cancelled = true;
-		};
+		doFetch().catch(() => {});
+		return () => controller.abort();
 	}, [documentId, searchSpaceId, title]);
 
 	const handleMarkdownChange = useCallback((md: string) => {
diff --git a/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx b/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx
index ac279cd4d..a645bfbd5 100644
--- a/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx
+++ b/surfsense_web/components/layout/ui/tabs/DocumentTabContent.tsx
@@ -55,7 +55,7 @@ export function DocumentTabContent({ documentId, searchSpaceId, title }: Documen
 	const changeCountRef = useRef(0);
 
 	useEffect(() => {
-		let cancelled = false;
+		const controller = new AbortController();
 		setIsLoading(true);
 		setError(null);
 		setDoc(null);
@@ -64,7 +64,7 @@ export function DocumentTabContent({ documentId, searchSpaceId, title }: Documen
 		initialLoadDone.current = false;
 		changeCountRef.current = 0;
 
-		const fetchContent = async () => {
+		const doFetch = async () => {
 			const token = getBearerToken();
 			if (!token) {
 				redirectToLogin();
@@ -74,10 +74,10 @@ export function DocumentTabContent({ documentId, searchSpaceId, title }: Documen
 			try {
 				const response = await authenticatedFetch(
 					`${process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL}/api/v1/search-spaces/${searchSpaceId}/documents/${documentId}/editor-content`,
-					{ method: "GET" }
+					{ method: "GET", signal: controller.signal }
 				);
 
-				if (cancelled) return;
+				if (controller.signal.aborted) return;
 
 				if (!response.ok) {
 					const errorData = await response
@@ -98,18 +98,16 @@ export function DocumentTabContent({ documentId, searchSpaceId, title }: Documen
 				setDoc(data);
 				initialLoadDone.current = true;
 			} catch (err) {
-				if (cancelled) return;
+				if (controller.signal.aborted) return;
 				console.error("Error fetching document:", err);
 				setError(err instanceof Error ? err.message : "Failed to fetch document");
 			} finally {
-				if (!cancelled) setIsLoading(false);
+				if (!controller.signal.aborted) setIsLoading(false);
 			}
 		};
 
-		fetchContent();
-		return () => {
-			cancelled = true;
-		};
+		doFetch().catch(() => {});
+		return () => controller.abort();
 	}, [documentId, searchSpaceId]);
 
 	const handleMarkdownChange = useCallback((md: string) => {

From 8eaa4e618ddf0b33aef539ba5da1ef54aab4b6bf Mon Sep 17 00:00:00 2001
From: SohamBhattacharjee2003
 <125297948+SohamBhattacharjee2003@users.noreply.github.com>
Date: Fri, 3 Apr 2026 14:42:44 +0530
Subject: [PATCH 59/70] perf(hooks): normalize query keys and add
 placeholderData to optimize thread loading

---
 .../components/layout/ui/sidebar/AllPrivateChatsSidebar.tsx   | 1 +
 surfsense_web/components/onboarding-tour.tsx                  | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/surfsense_web/components/layout/ui/sidebar/AllPrivateChatsSidebar.tsx b/surfsense_web/components/layout/ui/sidebar/AllPrivateChatsSidebar.tsx
index 1bc773374..63d69ecd1 100644
--- a/surfsense_web/components/layout/ui/sidebar/AllPrivateChatsSidebar.tsx
+++ b/surfsense_web/components/layout/ui/sidebar/AllPrivateChatsSidebar.tsx
@@ -109,6 +109,7 @@ export function AllPrivateChatsSidebarContent({
 		queryKey: ["all-threads", searchSpaceId],
 		queryFn: () => fetchThreads(Number(searchSpaceId)),
 		enabled: !!searchSpaceId && !isSearchMode,
+		placeholderData: () => queryClient.getQueryData(["threads", searchSpaceId, { limit: 40 }]),
 	});
 
 	const {
diff --git a/surfsense_web/components/onboarding-tour.tsx b/surfsense_web/components/onboarding-tour.tsx
index 1c52169cb..d35799137 100644
--- a/surfsense_web/components/onboarding-tour.tsx
+++ b/surfsense_web/components/onboarding-tour.tsx
@@ -439,8 +439,8 @@ export function OnboardingTour() {
 
 	// Fetch threads data
 	const { data: threadsData } = useQuery({
-		queryKey: ["threads", searchSpaceId, { limit: 1 }],
-		queryFn: () => fetchThreads(Number(searchSpaceId), 1), // Only need to check if any exist
+		queryKey: ["threads", searchSpaceId, { limit: 40 }], // Same key as layout
+		queryFn: () => fetchThreads(Number(searchSpaceId), 40),
 		enabled: !!searchSpaceId,
 	});
 

From 4131e6bea97a55eeafd3095f6aa09d93172d4bd1 Mon Sep 17 00:00:00 2001
From: SohamBhattacharjee2003
 <125297948+SohamBhattacharjee2003@users.noreply.github.com>
Date: Fri, 3 Apr 2026 14:49:45 +0530
Subject: [PATCH 60/70] Optimize tool-fallback by memoizing JSON.stringify to
 reduce render overhead

---
 .../components/assistant-ui/tool-fallback.tsx | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/tool-fallback.tsx b/surfsense_web/components/assistant-ui/tool-fallback.tsx
index 17d99549e..40118d2e4 100644
--- a/surfsense_web/components/assistant-ui/tool-fallback.tsx
+++ b/surfsense_web/components/assistant-ui/tool-fallback.tsx
@@ -1,6 +1,6 @@
 import type { ToolCallMessagePartComponent } from "@assistant-ui/react";
 import { CheckIcon, ChevronDownIcon, ChevronUpIcon, XCircleIcon } from "lucide-react";
-import { useState } from "react";
+import { useMemo, useState } from "react";
 import { getToolIcon } from "@/contracts/enums/toolIcons";
 import { cn } from "@/lib/utils";
 
@@ -19,17 +19,28 @@ export const ToolFallback: ToolCallMessagePartComponent = ({
 	const isCancelled = status?.type === "incomplete" && status.reason === "cancelled";
 	const isError = status?.type === "incomplete" && status.reason === "error";
 	const isRunning = status?.type === "running" || status?.type === "requires-action";
+	const errorData = status?.type === "incomplete" ? status.error : undefined;
+	const serializedError = useMemo(
+		() => (errorData && typeof errorData !== "string" ? JSON.stringify(errorData) : null),
+		[errorData]
+	);
+
+	const serializedResult = useMemo(
+		() => (result !== undefined && typeof result !== "string" ? JSON.stringify(result, null, 2) : null),
+		[result]
+	);
+
 	const cancelledReason =
 		isCancelled && status.error
 			? typeof status.error === "string"
 				? status.error
-				: JSON.stringify(status.error)
+				: serializedError
 			: null;
 	const errorReason =
 		isError && status.error
 			? typeof status.error === "string"
 				? status.error
-				: JSON.stringify(status.error)
+				: serializedError
 			: null;
 
 	const Icon = getToolIcon(toolName);
@@ -122,7 +133,7 @@ export const ToolFallback: ToolCallMessagePartComponent = ({
 								<div>
 									<p className="text-xs font-medium text-muted-foreground mb-1">Result</p>
 									<pre className="text-xs text-foreground/80 whitespace-pre-wrap break-all">
-										{typeof result === "string" ? result : JSON.stringify(result, null, 2)}
+										{typeof result === "string" ? result : serializedResult}
 									</pre>
 								</div>
 							</>

From 416b3635bf90d9c5618745f9069d2cab816839c0 Mon Sep 17 00:00:00 2001
From: sukarxn <thecodersmailbox@gmail.com>
Date: Fri, 3 Apr 2026 17:09:35 +0530
Subject: [PATCH 61/70] fix: optimize image components with next/image

- Replace raw <img> with Next.js Image in markdown-viewer.tsx
- Use next/image with fill + sizes in assistant-ui image.tsx
- Optimize favicons with explicit dimensions in citation components
- Set unoptimized=true for data/blob URLs and external favicons
---
 .../components/assistant-ui/image.tsx         | 121 +++++++++++++-----
 .../components/homepage/use-cases-grid.tsx    |  10 ++
 surfsense_web/components/markdown-viewer.tsx  |  37 ++++--
 .../tool-ui/citation/citation-list.tsx        |  42 +++---
 .../components/tool-ui/citation/citation.tsx  |  25 ++--
 5 files changed, 160 insertions(+), 75 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/image.tsx b/surfsense_web/components/assistant-ui/image.tsx
index 65059bcdc..c147eede4 100644
--- a/surfsense_web/components/assistant-ui/image.tsx
+++ b/surfsense_web/components/assistant-ui/image.tsx
@@ -6,6 +6,7 @@ import { ImageIcon, ImageOffIcon } from "lucide-react";
 import { memo, type PropsWithChildren, useEffect, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import { cn } from "@/lib/utils";
+import NextImage from 'next/image';
 
 const imageVariants = cva("aui-image-root relative overflow-hidden rounded-lg", {
 	variants: {
@@ -86,23 +87,57 @@ function ImagePreview({
 				>
 					<ImageOffIcon className="size-8 text-muted-foreground" />
 				</div>
-			) : (
+			) : isDataOrBlobUrl(src) ? (
+                // biome-ignore lint/performance/noImgElement: data/blob URLs need plain img
+                <img
+                    ref={imgRef}
+                    src={src}
+                    alt={alt}
+                    className={cn("block h-auto w-full object-contain", !loaded && "invisible", className)}
+                    onLoad={(e) => {
+                        if (typeof src === "string") setLoadedSrc(src);
+                        onLoad?.(e);
+                    }}
+                    onError={(e) => {
+                        if (typeof src === "string") setErrorSrc(src);
+                        onError?.(e);
+                    }}
+                    {...props}
+                />
+            ) : (
 				// biome-ignore lint/performance/noImgElement: intentional for dynamic external URLs
-				<img
-					ref={imgRef}
-					src={src}
-					alt={alt}
-					className={cn("block h-auto w-full object-contain", !loaded && "invisible", className)}
-					onLoad={(e) => {
-						if (typeof src === "string") setLoadedSrc(src);
-						onLoad?.(e);
-					}}
-					onError={(e) => {
-						if (typeof src === "string") setErrorSrc(src);
-						onError?.(e);
-					}}
-					{...props}
-				/>
+				// <img
+				// 	ref={imgRef}
+				// 	src={src}
+				// 	alt={alt}
+				// 	className={cn("block h-auto w-full object-contain", !loaded && "invisible", className)}
+				// 	onLoad={(e) => {
+				// 		if (typeof src === "string") setLoadedSrc(src);
+				// 		onLoad?.(e);
+				// 	}}
+				// 	onError={(e) => {
+				// 		if (typeof src === "string") setErrorSrc(src);
+				// 		onError?.(e);
+				// 	}}
+				// 	{...props}
+				// />
+				<NextImage
+				fill
+				src={src || ""}
+				alt={alt}
+				sizes="(max-width: 768px) 100vw, (max-width: 1200px) 80vw, 60vw"
+				className={cn("block object-contain", !loaded && "invisible", className)}
+				onLoad={() => {
+					if (typeof src === "string") setLoadedSrc(src);
+					onLoad?.();
+				}}
+				onError={() => {
+					if (typeof src === "string") setErrorSrc(src);
+					onError?.();
+				}}
+				unoptimized={false}
+				{...props}
+			/>
 			)}
 		</div>
 	);
@@ -126,7 +161,10 @@ type ImageZoomProps = PropsWithChildren<{
 	src: string;
 	alt?: string;
 }>;
-
+function isDataOrBlobUrl(src: string | undefined): boolean {
+    if (!src || typeof src !== "string") return false;
+    return src.startsWith("data:") || src.startsWith("blob:");
+}
 function ImageZoom({ src, alt = "Image preview", children }: ImageZoomProps) {
 	const [isMounted, setIsMounted] = useState(false);
 	const [isOpen, setIsOpen] = useState(false);
@@ -177,22 +215,39 @@ function ImageZoom({ src, alt = "Image preview", children }: ImageZoomProps) {
 						aria-label="Close zoomed image"
 					>
 						{/** biome-ignore lint/performance/noImgElement: <explanation> */}
-						<img
-							data-slot="image-zoom-content"
-							src={src}
-							alt={alt}
-							className="aui-image-zoom-content fade-in zoom-in-95 max-h-[90vh] max-w-[90vw] animate-in object-contain duration-200"
-							onClick={(e) => {
-								e.stopPropagation();
-								handleClose();
-							}}
-							onKeyDown={(e) => {
-								if (e.key === "Enter") {
-									e.stopPropagation();
-									handleClose();
-								}
-							}}
-						/>
+						{isDataOrBlobUrl(src) ? (
+                            // biome-ignore lint/performance/noImgElement: data/blob URLs need plain img
+                            <img
+                                data-slot="image-zoom-content"
+                                src={src}
+                                alt={alt}
+                                className="aui-image-zoom-content fade-in zoom-in-95 max-h-[90vh] max-w-[90vw] animate-in object-contain duration-200"
+                                onClick={(e) => {
+                                    e.stopPropagation();
+                                    handleClose();
+                                }}
+                                onKeyDown={(e) => {
+                                    if (e.key === "Enter") {
+                                        e.stopPropagation();
+                                        handleClose();
+                                    }
+                                }}
+                            />
+                        ) : (
+							<NextImage
+                                data-slot="image-zoom-content"
+                                fill
+                                src={src}
+                                alt={alt}
+                                sizes="90vw"
+                                className="aui-image-zoom-content fade-in zoom-in-95 object-contain duration-200"
+                                onClick={(e) => {
+                                    e.stopPropagation();
+                                    handleClose();
+                                }}
+                                unoptimized={false}
+                            />
+                        )}
 					</button>,
 					document.body
 				)}
diff --git a/surfsense_web/components/homepage/use-cases-grid.tsx b/surfsense_web/components/homepage/use-cases-grid.tsx
index 2f8c2d537..f9d315b49 100644
--- a/surfsense_web/components/homepage/use-cases-grid.tsx
+++ b/surfsense_web/components/homepage/use-cases-grid.tsx
@@ -1,4 +1,5 @@
 "use client";
+import Image from 'next/image';
 
 import { AnimatePresence, motion } from "motion/react";
 import { ExpandedGifOverlay, useExpandedGif } from "@/components/ui/expanded-gif-overlay";
@@ -81,6 +82,15 @@ function UseCaseCard({
 						alt={title}
 						className="w-full rounded-xl object-cover transition-transform duration-500 group-hover:scale-[1.02]"
 					/>
+					<div className="relative w-full h-48">
+					<Image
+						src={src}
+						alt={title}
+						fill
+						className="rounded-xl object-cover transition-transform duration-500 group-hover:scale-[1.02]"
+						unoptimized={src.endsWith('.gif')}
+					/>
+					</div>
 				</div>
 				<div className="px-5 py-4">
 					<h3 className="text-base font-semibold text-neutral-900 dark:text-white">{title}</h3>
diff --git a/surfsense_web/components/markdown-viewer.tsx b/surfsense_web/components/markdown-viewer.tsx
index a568bd698..1c39f03a0 100644
--- a/surfsense_web/components/markdown-viewer.tsx
+++ b/surfsense_web/components/markdown-viewer.tsx
@@ -3,6 +3,8 @@ import { createMathPlugin } from "@streamdown/math";
 import { Streamdown, type StreamdownProps } from "streamdown";
 import "katex/dist/katex.min.css";
 import { cn } from "@/lib/utils";
+import Image from 'next/image';
+import { is } from "drizzle-orm";
 
 const code = createCodePlugin({
 	themes: ["nord", "nord"],
@@ -127,16 +129,31 @@ export function MarkdownViewer({ content, className, maxLength }: MarkdownViewer
 			<blockquote className="border-l-4 border-muted pl-4 italic my-2" {...props} />
 		),
 		hr: ({ ...props }) => <hr className="my-4 border-muted" {...props} />,
-		img: ({ src, alt, width: _w, height: _h, ...props }) => (
-			// eslint-disable-next-line @next/next/no-img-element
-			<img
-				className="max-w-full h-auto my-4 rounded"
-				alt={alt || "markdown image"}
-				src={typeof src === "string" ? src : ""}
-				loading="lazy"
-				{...props}
-			/>
-		),
+		img: ({ src, alt, width: _w, height: _h, ...props }) => {
+    	const isDataOrUnknownUrl = typeof src === "string" && (src.startsWith("data:") || !src.startsWith("http"));
+
+    return isDataOrUnknownUrl ? (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img
+            className="max-w-full h-auto my-4 rounded"
+            alt={alt || "markdown image"}
+            src={src}
+            loading="lazy"
+            {...props}
+        />
+    ) : (
+        <Image
+            className="max-w-full h-auto my-4 rounded"
+            alt={alt || "markdown image"}
+            src={typeof src === "string" ? src : ""}
+            width={_w || 800}
+            height={_h || 600}
+            sizes="(max-width: 768px) 100vw, (max-width: 1200px) 75vw, 60vw"
+            unoptimized={isDataOrUnknownUrl}
+            {...props}
+        />
+    );
+},
 		table: ({ ...props }) => (
 			<div className="overflow-x-auto my-4 rounded-lg border border-border w-full">
 				<table className="w-full divide-y divide-border" {...props} />
diff --git a/surfsense_web/components/tool-ui/citation/citation-list.tsx b/surfsense_web/components/tool-ui/citation/citation-list.tsx
index 3151917b6..75b02bf3d 100644
--- a/surfsense_web/components/tool-ui/citation/citation-list.tsx
+++ b/surfsense_web/components/tool-ui/citation/citation-list.tsx
@@ -7,6 +7,8 @@ import { openSafeNavigationHref, resolveSafeNavigationHref } from "../shared/med
 import { cn, Popover, PopoverContent, PopoverTrigger } from "./_adapter";
 import { Citation } from "./citation";
 import type { CitationType, CitationVariant, SerializableCitation } from "./schema";
+import NextImage from 'next/image';
+
 
 const TYPE_ICONS: Record<CitationType, LucideIcon> = {
 	webpage: Globe,
@@ -253,18 +255,18 @@ function OverflowItem({ citation, onClick }: OverflowItemProps) {
 			className="group hover:bg-muted focus-visible:bg-muted flex w-full cursor-pointer items-center gap-2.5 rounded-md px-2 py-2 text-left transition-colors focus-visible:outline-none"
 		>
 			{citation.favicon ? (
-				// biome-ignore lint/performance/noImgElement: external favicon from arbitrary domain — next/image requires remotePatterns config
-				<img
+				<NextImage
 					src={citation.favicon}
 					alt=""
 					aria-hidden="true"
-					width={16}
-					height={16}
-					className="bg-muted size-4 shrink-0 rounded object-cover"
+					width={18}
+					height={18}
+					className="size-4.5 rounded-full object-cover"
+					unoptimized={true}
 				/>
-			) : (
-				<TypeIcon className="text-muted-foreground size-4 shrink-0" aria-hidden="true" />
-			)}
+				) : (
+				<TypeIcon className="text-muted-foreground size-3" aria-hidden="true" />
+				)}
 			<div className="min-w-0 flex-1">
 				<p className="group-hover:decoration-foreground/30 truncate text-sm font-medium group-hover:underline group-hover:underline-offset-2">
 					{citation.title}
@@ -339,18 +341,18 @@ function StackedCitations({ id, citations, className, onNavigate }: StackedCitat
 										style={{ zIndex: maxIcons - index }}
 									>
 										{citation.favicon ? (
-											// biome-ignore lint/performance/noImgElement: external favicon from arbitrary domain — next/image requires remotePatterns config
-											<img
-												src={citation.favicon}
-												alt=""
-												aria-hidden="true"
-												width={18}
-												height={18}
-												className="size-4.5 rounded-full object-cover"
-											/>
-										) : (
-											<TypeIcon className="text-muted-foreground size-3" aria-hidden="true" />
-										)}
+										<NextImage
+											src={citation.favicon}
+											alt=""
+											aria-hidden="true"
+											width={18}
+											height={18}
+											className="size-4.5 rounded-full object-cover"
+											unoptimized={true}
+										/>
+									) : (
+										<TypeIcon className="text-muted-foreground size-3" aria-hidden="true" />
+									)}	
 									</div>
 								);
 							})}
diff --git a/surfsense_web/components/tool-ui/citation/citation.tsx b/surfsense_web/components/tool-ui/citation/citation.tsx
index 523169f49..fa5d4d165 100644
--- a/surfsense_web/components/tool-ui/citation/citation.tsx
+++ b/surfsense_web/components/tool-ui/citation/citation.tsx
@@ -6,6 +6,7 @@ import * as React from "react";
 import { openSafeNavigationHref, sanitizeHref } from "../shared/media";
 import { cn, Popover, PopoverContent, PopoverTrigger } from "./_adapter";
 import type { CitationType, CitationVariant, SerializableCitation } from "./schema";
+import NextImage from 'next/image';
 
 const FALLBACK_LOCALE = "en-US";
 
@@ -114,18 +115,18 @@ export function Citation(props: CitationProps) {
 	};
 
 	const iconElement = favicon ? (
-		// biome-ignore lint/performance/noImgElement: external favicon from arbitrary domain — next/image requires remotePatterns config
-		<img
-			src={favicon}
-			alt=""
-			aria-hidden="true"
-			width={14}
-			height={14}
-			className="bg-muted size-3.5 shrink-0 rounded object-cover"
-		/>
-	) : (
-		<TypeIcon className="size-3.5 shrink-0 opacity-60" aria-hidden="true" />
-	);
+    <NextImage
+        src={favicon}
+        alt=""
+        aria-hidden="true"
+        width={16}
+        height={16}
+        className="bg-muted size-3.5 shrink-0 rounded object-cover"
+        unoptimized={true}
+    />
+) : (
+    <TypeIcon className="size-3.5 shrink-0 opacity-60" aria-hidden="true" />
+);
 
 	const { open, handleMouseEnter, handleMouseLeave } = useHoverPopover();
 

From 1c50106c819fd6adceb6a78b7a5cb0e6c7eb0309 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 17:24:06 +0530
Subject: [PATCH 62/70] refactor: simplify file upload logic in
 DocumentUploadTab by removing file count and size limits; update file size
 limit messages in multiple languages

---
 .../assistant-ui/document-upload-popup.tsx    |  2 +-
 .../components/sources/DocumentUploadTab.tsx  | 73 +++----------------
 surfsense_web/messages/en.json                | 15 +---
 surfsense_web/messages/es.json                | 15 +---
 surfsense_web/messages/hi.json                | 15 +---
 surfsense_web/messages/pt.json                | 15 +---
 surfsense_web/messages/zh.json                | 15 +---
 7 files changed, 30 insertions(+), 120 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/document-upload-popup.tsx b/surfsense_web/components/assistant-ui/document-upload-popup.tsx
index 4f06588c1..59d73e651 100644
--- a/surfsense_web/components/assistant-ui/document-upload-popup.tsx
+++ b/surfsense_web/components/assistant-ui/document-upload-popup.tsx
@@ -125,7 +125,7 @@ const DocumentUploadPopupContent: FC<{
 				onPointerDownOutside={(e) => e.preventDefault()}
 				onInteractOutside={(e) => e.preventDefault()}
 				onEscapeKeyDown={(e) => e.preventDefault()}
-				className="select-none max-w-2xl w-[95vw] sm:w-[640px] h-[min(460px,75dvh)] sm:h-[min(520px,80vh)] flex flex-col p-0 gap-0 overflow-hidden border border-border ring-0 bg-muted dark:bg-muted text-foreground [&>button]:right-3 sm:[&>button]:right-6 [&>button]:top-3 sm:[&>button]:top-5 [&>button]:opacity-80 hover:[&>button]:opacity-100 [&>button]:z-[100] [&>button_svg]:size-4 sm:[&>button_svg]:size-5"
+				className="select-none max-w-2xl w-[95vw] sm:w-[640px] h-[min(440px,75dvh)] sm:h-[min(500px,80vh)] flex flex-col p-0 gap-0 overflow-hidden border border-border ring-0 bg-muted dark:bg-muted text-foreground [&>button]:right-3 sm:[&>button]:right-6 [&>button]:top-3 sm:[&>button]:top-5 [&>button]:opacity-80 hover:[&>button]:opacity-100 [&>button]:z-[100] [&>button_svg]:size-4 sm:[&>button_svg]:size-5"
 			>
 				<DialogTitle className="sr-only">Upload Document</DialogTitle>
 
diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index 940d1560a..dcafe62ba 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -121,10 +121,6 @@ interface FileWithId {
 	file: File;
 }
 
-const MAX_FILES = 50;
-const MAX_TOTAL_SIZE_MB = 200;
-const MAX_TOTAL_SIZE_BYTES = MAX_TOTAL_SIZE_MB * 1024 * 1024;
-
 const MAX_FILE_SIZE_MB = 500;
 const MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024;
 
@@ -204,7 +200,6 @@ export function DocumentUploadTab({
 		accept: acceptedFileTypes,
 		maxSize: MAX_FILE_SIZE_BYTES,
 		noClick: isElectron,
-		disabled: files.length >= MAX_FILES,
 	});
 
 	const handleFileInputClick = useCallback((e: React.MouseEvent<HTMLInputElement>) => {
@@ -224,24 +219,8 @@ export function DocumentUploadTab({
 			id: crypto.randomUUID?.() ?? `file-${Date.now()}-${Math.random().toString(36)}`,
 			file: new File([fd.data], fd.name, { type: fd.mimeType }),
 		}));
-		setFiles((prev) => {
-			const merged = [...prev, ...newFiles];
-			if (merged.length > MAX_FILES) {
-				toast.error(t("max_files_exceeded"), {
-					description: t("max_files_exceeded_desc", { max: MAX_FILES }),
-				});
-				return prev;
-			}
-			const totalSize = merged.reduce((sum, e) => sum + e.file.size, 0);
-			if (totalSize > MAX_TOTAL_SIZE_BYTES) {
-				toast.error(t("max_size_exceeded"), {
-					description: t("max_size_exceeded_desc", { max: MAX_TOTAL_SIZE_MB }),
-				});
-				return prev;
-			}
-			return merged;
-		});
-	}, [t]);
+		setFiles((prev) => [...prev, ...newFiles]);
+	}, []);
 
 	const handleBrowseFolder = useCallback(async () => {
 		const api = window.electronAPI;
@@ -288,14 +267,6 @@ export function DocumentUploadTab({
 
 	const totalFileSize = files.reduce((total, entry) => total + entry.file.size, 0);
 
-	const isFileCountLimitReached = files.length >= MAX_FILES;
-	const isSizeLimitReached = totalFileSize >= MAX_TOTAL_SIZE_BYTES;
-	const remainingFiles = MAX_FILES - files.length;
-	const remainingSizeMB = Math.max(
-		0,
-		(MAX_TOTAL_SIZE_BYTES - totalFileSize) / (1024 * 1024)
-	).toFixed(1);
-
 	const hasContent = files.length > 0 || selectedFolder !== null;
 
 	const handleAccordionChange = useCallback(
@@ -392,8 +363,6 @@ export function DocumentUploadTab({
 
 	const renderBrowseButton = (options?: { compact?: boolean; fullWidth?: boolean }) => {
 		const { compact, fullWidth } = options ?? {};
-		if (isFileCountLimitReached) return null;
-
 		const sizeClass = compact ? "h-7" : "h-8";
 		const widthClass = fullWidth ? "w-full" : "";
 
@@ -478,7 +447,6 @@ export function DocumentUploadTab({
 			<div className="sm:hidden">
 				{hasContent ? (
 					!selectedFolder &&
-					!isFileCountLimitReached &&
 					(isElectron ? (
 						<div className="w-full">{renderBrowseButton({ compact: true, fullWidth: true })}</div>
 					) : (
@@ -502,12 +470,8 @@ export function DocumentUploadTab({
 							<p className="text-base font-medium">
 								{isElectron ? "Select files or folder" : "Tap to select files or folder"}
 							</p>
-							<p className="text-sm text-muted-foreground inline-flex items-center flex-wrap justify-center">
-								<span>{t("file_size_limit")}</span>
-								<Dot className="h-4 w-4 shrink-0" />
-								<span>
-									{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}
-								</span>
+							<p className="text-sm text-muted-foreground">
+								{t("file_size_limit")}
 							</p>
 						</div>
 						<div className="w-full mt-1" onClick={(e) => e.stopPropagation()}>
@@ -520,11 +484,7 @@ export function DocumentUploadTab({
 			{/* DESKTOP DROP ZONE */}
 			<div
 				{...getRootProps()}
-				className={`hidden sm:block border-2 border-dashed rounded-lg transition-colors ${
-					isFileCountLimitReached || isSizeLimitReached
-						? "border-destructive/50 bg-destructive/5 cursor-not-allowed"
-						: "border-muted-foreground/30 hover:border-foreground/70 cursor-pointer"
-				} ${hasContent ? "p-3" : "py-20 px-4"}`}
+				className={`hidden sm:block border-2 border-dashed rounded-lg transition-colors border-muted-foreground/30 hover:border-foreground/70 cursor-pointer ${hasContent ? "p-3" : "py-20 px-4"}`}
 			>
 				{hasContent ? (
 					<div className="flex items-center gap-3">
@@ -532,20 +492,10 @@ export function DocumentUploadTab({
 						<span className="text-xs text-muted-foreground flex-1 truncate">
 							{isDragActive
 								? t("drop_files")
-								: isFileCountLimitReached
-									? t("file_limit_reached")
-									: t("remaining_capacity", { files: remainingFiles, sizeMB: remainingSizeMB })}
+								: t("drag_drop_more")}
 						</span>
 						{renderBrowseButton({ compact: true })}
 					</div>
-				) : isFileCountLimitReached ? (
-					<div className="flex flex-col items-center gap-2 text-center">
-						<Upload className="h-8 w-8 text-destructive/70" />
-						<p className="text-sm font-medium text-destructive">{t("file_limit_reached")}</p>
-						<p className="text-xs text-muted-foreground">
-							{t("file_limit_reached_desc", { max: MAX_FILES })}
-						</p>
-					</div>
 				) : isDragActive ? (
 					<div className="flex flex-col items-center gap-2">
 						<Upload className="h-8 w-8 text-primary" />
@@ -555,12 +505,8 @@ export function DocumentUploadTab({
 					<div className="flex flex-col items-center gap-2">
 						<Upload className="h-8 w-8 text-muted-foreground" />
 						<p className="text-sm font-medium">{t("drag_drop")}</p>
-						<p className="text-xs text-muted-foreground text-center inline-flex items-center flex-wrap justify-center">
-							<span>{t("file_size_limit")}</span>
-							<Dot className="h-4 w-4 shrink-0" />
-							<span>
-								{t("upload_limits", { maxFiles: MAX_FILES, maxSizeMB: MAX_TOTAL_SIZE_MB })}
-							</span>
+						<p className="text-xs text-muted-foreground">
+							{t("file_size_limit")}
 						</p>
 						<div className="mt-1">{renderBrowseButton()}</div>
 					</div>
@@ -632,8 +578,7 @@ export function DocumentUploadTab({
 				<div className="rounded-lg border border-border p-3 space-y-2">
 					<div className="flex items-center justify-between">
 						<p className="text-sm font-medium">
-							{t("selected_files", { count: files.length })} &middot;{" "}
-							{formatFileSize(totalFileSize)}
+							{t("selected_files", { count: files.length })}<Dot className="inline h-4 w-4" />{formatFileSize(totalFileSize)}
 						</p>
 						<Button
 							variant="ghost"
diff --git a/surfsense_web/messages/en.json b/surfsense_web/messages/en.json
index 3a8c0c632..2e6e79976 100644
--- a/surfsense_web/messages/en.json
+++ b/surfsense_web/messages/en.json
@@ -376,14 +376,14 @@
 	"upload_documents": {
 		"title": "Upload Documents",
 		"subtitle": "Upload your files to make them searchable and accessible through AI-powered conversations.",
-		"file_size_limit": "Maximum file size: 50MB per file",
-		"upload_limits": "Upload limit: {maxFiles} files, {maxSizeMB}MB total",
+		"file_size_limit": "Maximum file size: 500MB per file",
 		"drop_files": "Drop files or folders here",
 		"drag_drop": "Drag & drop files or folders here",
+		"drag_drop_more": "Drop or browse to add more files",
 		"or_browse": "or click to browse",
 		"browse_files": "Browse Files",
 		"browse_folder": "Browse Folder",
-		"selected_files": "Selected Files ({count})",
+		"selected_files": "{count} selected {count, plural, one {file} other {files}}",
 		"total_size": "Total size",
 		"clear_all": "Clear all",
 		"uploading_files": "Uploading files",
@@ -397,14 +397,7 @@
 		"file_types_desc": "These file types are supported based on your current ETL service configuration.",
 		"file_too_large": "File Too Large",
 		"file_too_large_desc": "\"{name}\" exceeds the {maxMB}MB per-file limit.",
-		"no_supported_files_in_folder": "No supported file types found in the selected folder.",
-		"remaining_capacity": "{files} files, {sizeMB}MB remaining",
-		"file_limit_reached": "File limit reached",
-		"file_limit_reached_desc": "Maximum of {max} files allowed",
-		"max_files_exceeded": "Too many files",
-		"max_files_exceeded_desc": "You can upload a maximum of {max} files at once",
-		"max_size_exceeded": "Total size exceeded",
-		"max_size_exceeded_desc": "Total upload size cannot exceed {max}MB"
+		"no_supported_files_in_folder": "No supported file types found in the selected folder."
 	},
 	"add_webpage": {
 		"title": "Add Webpages for Crawling",
diff --git a/surfsense_web/messages/es.json b/surfsense_web/messages/es.json
index 2de30d29d..e282a52e1 100644
--- a/surfsense_web/messages/es.json
+++ b/surfsense_web/messages/es.json
@@ -376,14 +376,14 @@
 	"upload_documents": {
 		"title": "Subir documentos",
 		"subtitle": "Sube tus archivos para hacerlos buscables y accesibles a través de conversaciones con IA.",
-		"file_size_limit": "Tamaño máximo de archivo: 50 MB por archivo",
-		"upload_limits": "Límite de subida: {maxFiles} archivos, {maxSizeMB} MB en total",
+		"file_size_limit": "Tamaño máximo de archivo: 500 MB por archivo",
 		"drop_files": "Suelta archivos o carpetas aquí",
 		"drag_drop": "Arrastra y suelta archivos o carpetas aquí",
+		"drag_drop_more": "Suelta o explora para agregar más archivos",
 		"or_browse": "o haz clic para explorar",
 		"browse_files": "Explorar archivos",
 		"browse_folder": "Explorar carpeta",
-		"selected_files": "Archivos seleccionados ({count})",
+		"selected_files": "{count} {count, plural, one {archivo seleccionado} other {archivos seleccionados}}",
 		"total_size": "Tamaño total",
 		"clear_all": "Limpiar todo",
 		"uploading_files": "Subiendo archivos",
@@ -397,14 +397,7 @@
 		"file_types_desc": "Estos tipos de archivo son soportados según la configuración actual de tu servicio ETL.",
 		"file_too_large": "Archivo demasiado grande",
 		"file_too_large_desc": "\"{name}\" excede el límite de {maxMB} MB por archivo.",
-		"no_supported_files_in_folder": "No se encontraron tipos de archivo compatibles en la carpeta seleccionada.",
-		"remaining_capacity": "{files} archivos, {sizeMB}MB restante",
-		"file_limit_reached": "Límite de archivos alcanzado",
-		"file_limit_reached_desc": "Máximo de {max} archivos permitidos",
-		"max_files_exceeded": "Demasiados archivos",
-		"max_files_exceeded_desc": "Puedes subir un máximo de {max} archivos a la vez",
-		"max_size_exceeded": "Tamaño total excedido",
-		"max_size_exceeded_desc": "El tamaño total de subida no puede exceder {max}MB"
+		"no_supported_files_in_folder": "No se encontraron tipos de archivo compatibles en la carpeta seleccionada."
 	},
 	"add_webpage": {
 		"title": "Agregar páginas web para rastreo",
diff --git a/surfsense_web/messages/hi.json b/surfsense_web/messages/hi.json
index c27291e3b..9d4d982ad 100644
--- a/surfsense_web/messages/hi.json
+++ b/surfsense_web/messages/hi.json
@@ -376,14 +376,14 @@
 	"upload_documents": {
 		"title": "दस्तावेज़ अपलोड करें",
 		"subtitle": "AI-संचालित बातचीत के माध्यम से अपनी फ़ाइलों को खोजने योग्य और सुलभ बनाने के लिए अपलोड करें।",
-		"file_size_limit": "अधिकतम फ़ाइल आकार: प्रति फ़ाइल 50MB",
-		"upload_limits": "अपलोड सीमा: {maxFiles} फ़ाइलें, कुल {maxSizeMB}MB",
+		"file_size_limit": "अधिकतम फ़ाइल आकार: प्रति फ़ाइल 500MB",
 		"drop_files": "फ़ाइलें या फ़ोल्डर यहां छोड़ें",
 		"drag_drop": "फ़ाइलें या फ़ोल्डर यहां खींचें और छोड़ें",
+		"drag_drop_more": "और फ़ाइलें जोड़ने के लिए छोड़ें या ब्राउज़ करें",
 		"or_browse": "या ब्राउज़ करने के लिए क्लिक करें",
 		"browse_files": "फ़ाइलें ब्राउज़ करें",
 		"browse_folder": "फ़ोल्डर ब्राउज़ करें",
-		"selected_files": "चयनित फ़ाइलें ({count})",
+		"selected_files": "{count} चयनित {count, plural, one {फ़ाइल} other {फ़ाइलें}}",
 		"total_size": "कुल आकार",
 		"clear_all": "सभी साफ करें",
 		"uploading_files": "फ़ाइलें अपलोड हो रही हैं",
@@ -397,14 +397,7 @@
 		"file_types_desc": "ये फ़ाइल प्रकार आपकी वर्तमान ETL सेवा कॉन्फ़िगरेशन के आधार पर समर्थित हैं।",
 		"file_too_large": "फ़ाइल बहुत बड़ी है",
 		"file_too_large_desc": "\"{name}\" प्रति फ़ाइल {maxMB}MB की सीमा से अधिक है।",
-		"no_supported_files_in_folder": "चयनित फ़ोल्डर में कोई समर्थित फ़ाइल प्रकार नहीं मिला।",
-		"remaining_capacity": "{files} फ़ाइलें, {sizeMB}MB शेष",
-		"file_limit_reached": "फ़ाइल सीमा पूरी हो गई",
-		"file_limit_reached_desc": "अधिकतम {max} फ़ाइलें अनुमत हैं",
-		"max_files_exceeded": "बहुत सारी फ़ाइलें",
-		"max_files_exceeded_desc": "आप एक बार में अधिकतम {max} फ़ाइलें अपलोड कर सकते हैं",
-		"max_size_exceeded": "कुल आकार सीमा पार",
-		"max_size_exceeded_desc": "कुल अपलोड आकार {max}MB से अधिक नहीं हो सकता"
+		"no_supported_files_in_folder": "चयनित फ़ोल्डर में कोई समर्थित फ़ाइल प्रकार नहीं मिला।"
 	},
 	"add_webpage": {
 		"title": "क्रॉलिंग के लिए वेबपेज जोड़ें",
diff --git a/surfsense_web/messages/pt.json b/surfsense_web/messages/pt.json
index eeb417a27..7cb28d12f 100644
--- a/surfsense_web/messages/pt.json
+++ b/surfsense_web/messages/pt.json
@@ -376,14 +376,14 @@
 	"upload_documents": {
 		"title": "Enviar documentos",
 		"subtitle": "Envie seus arquivos para torná-los pesquisáveis e acessíveis através de conversas com IA.",
-		"file_size_limit": "Tamanho máximo do arquivo: 50 MB por arquivo",
-		"upload_limits": "Limite de envio: {maxFiles} arquivos, {maxSizeMB} MB no total",
+		"file_size_limit": "Tamanho máximo do arquivo: 500 MB por arquivo",
 		"drop_files": "Solte arquivos ou pastas aqui",
 		"drag_drop": "Arraste e solte arquivos ou pastas aqui",
+		"drag_drop_more": "Solte ou navegue para adicionar mais arquivos",
 		"or_browse": "ou clique para navegar",
 		"browse_files": "Navegar arquivos",
 		"browse_folder": "Navegar pasta",
-		"selected_files": "Arquivos selecionados ({count})",
+		"selected_files": "{count} {count, plural, one {arquivo selecionado} other {arquivos selecionados}}",
 		"total_size": "Tamanho total",
 		"clear_all": "Limpar tudo",
 		"uploading_files": "Enviando arquivos",
@@ -397,14 +397,7 @@
 		"file_types_desc": "Estes tipos de arquivo são suportados com base na configuração atual do seu serviço ETL.",
 		"file_too_large": "Arquivo muito grande",
 		"file_too_large_desc": "\"{name}\" excede o limite de {maxMB} MB por arquivo.",
-		"no_supported_files_in_folder": "Nenhum tipo de arquivo suportado encontrado na pasta selecionada.",
-		"remaining_capacity": "{files} arquivos, {sizeMB}MB restante",
-		"file_limit_reached": "Limite de arquivos atingido",
-		"file_limit_reached_desc": "Máximo de {max} arquivos permitidos",
-		"max_files_exceeded": "Muitos arquivos",
-		"max_files_exceeded_desc": "Você pode enviar no máximo {max} arquivos de uma vez",
-		"max_size_exceeded": "Tamanho total excedido",
-		"max_size_exceeded_desc": "O tamanho total do envio não pode exceder {max}MB"
+		"no_supported_files_in_folder": "Nenhum tipo de arquivo suportado encontrado na pasta selecionada."
 	},
 	"add_webpage": {
 		"title": "Adicionar páginas web para rastreamento",
diff --git a/surfsense_web/messages/zh.json b/surfsense_web/messages/zh.json
index 2ee18a346..9d0108ebc 100644
--- a/surfsense_web/messages/zh.json
+++ b/surfsense_web/messages/zh.json
@@ -360,14 +360,14 @@
 	"upload_documents": {
 		"title": "上传文档",
 		"subtitle": "上传您的文件，使其可通过 AI 对话进行搜索和访问。",
-		"file_size_limit": "最大文件大小：每个文件 50MB",
-		"upload_limits": "上传限制：最多 {maxFiles} 个文件，总大小不超过 {maxSizeMB}MB",
+		"file_size_limit": "最大文件大小：每个文件 500MB",
 		"drop_files": "将文件或文件夹拖放到此处",
 		"drag_drop": "拖放文件或文件夹到这里",
+		"drag_drop_more": "拖放或浏览以添加更多文件",
 		"or_browse": "或点击浏览",
 		"browse_files": "浏览文件",
 		"browse_folder": "浏览文件夹",
-		"selected_files": "已选择的文件 ({count})",
+		"selected_files": "已选择 {count} 个文件",
 		"total_size": "总大小",
 		"clear_all": "全部清除",
 		"uploading_files": "正在上传文件...",
@@ -381,14 +381,7 @@
 		"file_types_desc": "根据您当前的 ETL 服务配置支持这些文件类型。",
 		"file_too_large": "文件过大",
 		"file_too_large_desc": "\"{name}\" 超过了每个文件 {maxMB}MB 的限制。",
-		"no_supported_files_in_folder": "所选文件夹中没有找到支持的文件类型。",
-		"remaining_capacity": "剩余 {files} 个文件，{sizeMB}MB",
-		"file_limit_reached": "已达文件数量上限",
-		"file_limit_reached_desc": "最多允许 {max} 个文件",
-		"max_files_exceeded": "文件数量过多",
-		"max_files_exceeded_desc": "一次最多上传 {max} 个文件",
-		"max_size_exceeded": "总大小超出限制",
-		"max_size_exceeded_desc": "总上传大小不能超过 {max}MB"
+		"no_supported_files_in_folder": "所选文件夹中没有找到支持的文件类型。"
 	},
 	"add_webpage": {
 		"title": "添加网页爬取",

From b7f916c4dfcc55d3cb84ab4d8a82a432ab6f6b8b Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 17:24:34 +0530
Subject: [PATCH 63/70] chore: ran linting

---
 .../components/sources/DocumentUploadTab.tsx     | 16 ++++++----------
 1 file changed, 6 insertions(+), 10 deletions(-)

diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index dcafe62ba..2d70a4e1a 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -470,9 +470,7 @@ export function DocumentUploadTab({
 							<p className="text-base font-medium">
 								{isElectron ? "Select files or folder" : "Tap to select files or folder"}
 							</p>
-							<p className="text-sm text-muted-foreground">
-								{t("file_size_limit")}
-							</p>
+							<p className="text-sm text-muted-foreground">{t("file_size_limit")}</p>
 						</div>
 						<div className="w-full mt-1" onClick={(e) => e.stopPropagation()}>
 							{renderBrowseButton({ fullWidth: true })}
@@ -490,9 +488,7 @@ export function DocumentUploadTab({
 					<div className="flex items-center gap-3">
 						<Upload className="h-4 w-4 text-muted-foreground shrink-0" />
 						<span className="text-xs text-muted-foreground flex-1 truncate">
-							{isDragActive
-								? t("drop_files")
-								: t("drag_drop_more")}
+							{isDragActive ? t("drop_files") : t("drag_drop_more")}
 						</span>
 						{renderBrowseButton({ compact: true })}
 					</div>
@@ -505,9 +501,7 @@ export function DocumentUploadTab({
 					<div className="flex flex-col items-center gap-2">
 						<Upload className="h-8 w-8 text-muted-foreground" />
 						<p className="text-sm font-medium">{t("drag_drop")}</p>
-						<p className="text-xs text-muted-foreground">
-							{t("file_size_limit")}
-						</p>
+						<p className="text-xs text-muted-foreground">{t("file_size_limit")}</p>
 						<div className="mt-1">{renderBrowseButton()}</div>
 					</div>
 				)}
@@ -578,7 +572,9 @@ export function DocumentUploadTab({
 				<div className="rounded-lg border border-border p-3 space-y-2">
 					<div className="flex items-center justify-between">
 						<p className="text-sm font-medium">
-							{t("selected_files", { count: files.length })}<Dot className="inline h-4 w-4" />{formatFileSize(totalFileSize)}
+							{t("selected_files", { count: files.length })}
+							<Dot className="inline h-4 w-4" />
+							{formatFileSize(totalFileSize)}
 						</p>
 						<Button
 							variant="ghost"

From 9d4c2f5b984442b89ebfe27b7173b83164470bfa Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 17:28:12 +0530
Subject: [PATCH 64/70] refactor: replace span with Dot component in public
 chat snapshots, model configuration and thread managers

---
 surfsense_web/components/assistant-ui/thread.tsx           | 7 ++++++-
 .../public-chat-snapshots/public-chat-snapshot-row.tsx     | 4 ++--
 surfsense_web/components/settings/image-model-manager.tsx  | 4 ++--
 surfsense_web/components/settings/model-config-manager.tsx | 3 ++-
 4 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/surfsense_web/components/assistant-ui/thread.tsx b/surfsense_web/components/assistant-ui/thread.tsx
index 818644a47..9e2869d4e 100644
--- a/surfsense_web/components/assistant-ui/thread.tsx
+++ b/surfsense_web/components/assistant-ui/thread.tsx
@@ -15,6 +15,7 @@ import {
 	ChevronDown,
 	ChevronUp,
 	Clipboard,
+	Dot,
 	Globe,
 	Plus,
 	Settings2,
@@ -1147,7 +1148,11 @@ const ComposerAction: FC<ComposerActionProps> = ({ isBlockedByOtherUser = false
 														<TooltipTrigger asChild>{row}</TooltipTrigger>
 														<TooltipContent side="right" className="max-w-72 text-xs">
 															{groupDef?.tooltip ??
-																group.tools.map((t) => t.description).join(" · ")}
+																group.tools.flatMap((t, i) =>
+																	i === 0
+																		? [t.description]
+																		: [<Dot key={i} className="inline h-4 w-4" />, t.description]
+																)}
 														</TooltipContent>
 													</Tooltip>
 												);
diff --git a/surfsense_web/components/public-chat-snapshots/public-chat-snapshot-row.tsx b/surfsense_web/components/public-chat-snapshots/public-chat-snapshot-row.tsx
index ddf4746aa..4bb49c48d 100644
--- a/surfsense_web/components/public-chat-snapshots/public-chat-snapshot-row.tsx
+++ b/surfsense_web/components/public-chat-snapshots/public-chat-snapshot-row.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { Check, Copy, ExternalLink, MessageSquare, Trash2 } from "lucide-react";
+import { Check, Copy, Dot, ExternalLink, MessageSquare, Trash2 } from "lucide-react";
 import { useCallback, useRef, useState } from "react";
 import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
 import { Badge } from "@/components/ui/badge";
@@ -153,7 +153,7 @@ export function PublicChatSnapshotRow({
 					<span className="text-[11px] text-muted-foreground/60">{formattedDate}</span>
 					{member && (
 						<>
-							<span className="text-muted-foreground/30">·</span>
+							<Dot className="h-4 w-4 text-muted-foreground/30" />
 							<TooltipProvider>
 								<Tooltip open={isDesktop ? undefined : false}>
 									<TooltipTrigger asChild>
diff --git a/surfsense_web/components/settings/image-model-manager.tsx b/surfsense_web/components/settings/image-model-manager.tsx
index 55128dc59..23162b629 100644
--- a/surfsense_web/components/settings/image-model-manager.tsx
+++ b/surfsense_web/components/settings/image-model-manager.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { useAtomValue } from "jotai";
-import { AlertCircle, Edit3, Info, RefreshCw, Trash2, Wand2 } from "lucide-react";
+import { AlertCircle, Dot, Edit3, Info, RefreshCw, Trash2, Wand2 } from "lucide-react";
 import { useMemo, useState } from "react";
 import { deleteImageGenConfigMutationAtom } from "@/atoms/image-gen-config/image-gen-config-mutation.atoms";
 import {
@@ -330,7 +330,7 @@ export function ImageModelManager({ searchSpaceId }: ImageModelManagerProps) {
 													</span>
 													{member && (
 														<>
-															<span className="text-muted-foreground/30">·</span>
+															<Dot className="h-4 w-4 text-muted-foreground/30" />
 															<TooltipProvider>
 																<Tooltip open={isDesktop ? undefined : false}>
 																	<TooltipTrigger asChild>
diff --git a/surfsense_web/components/settings/model-config-manager.tsx b/surfsense_web/components/settings/model-config-manager.tsx
index 79504451a..db4f169f8 100644
--- a/surfsense_web/components/settings/model-config-manager.tsx
+++ b/surfsense_web/components/settings/model-config-manager.tsx
@@ -3,6 +3,7 @@
 import { useAtomValue } from "jotai";
 import {
 	AlertCircle,
+	Dot,
 	Edit3,
 	FileText,
 	Info,
@@ -364,7 +365,7 @@ export function ModelConfigManager({ searchSpaceId }: ModelConfigManagerProps) {
 													</span>
 													{member && (
 														<>
-															<span className="text-muted-foreground/30">·</span>
+															<Dot className="h-4 w-4 text-muted-foreground/30" />
 															<TooltipProvider>
 																<Tooltip open={isDesktop ? undefined : false}>
 																	<TooltipTrigger asChild>

From 6f4c0d5e6c882c2aa6e73f8f2f29624418982e85 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 17:29:12 +0530
Subject: [PATCH 65/70] chore: remove redundant file types description

---
 surfsense_web/messages/en.json | 1 -
 surfsense_web/messages/es.json | 1 -
 surfsense_web/messages/hi.json | 1 -
 surfsense_web/messages/pt.json | 1 -
 surfsense_web/messages/zh.json | 1 -
 5 files changed, 5 deletions(-)

diff --git a/surfsense_web/messages/en.json b/surfsense_web/messages/en.json
index 2e6e79976..b67f9db22 100644
--- a/surfsense_web/messages/en.json
+++ b/surfsense_web/messages/en.json
@@ -394,7 +394,6 @@
 		"upload_error": "Upload Error",
 		"upload_error_desc": "Error uploading files",
 		"supported_file_types": "Supported File Types",
-		"file_types_desc": "These file types are supported based on your current ETL service configuration.",
 		"file_too_large": "File Too Large",
 		"file_too_large_desc": "\"{name}\" exceeds the {maxMB}MB per-file limit.",
 		"no_supported_files_in_folder": "No supported file types found in the selected folder."
diff --git a/surfsense_web/messages/es.json b/surfsense_web/messages/es.json
index e282a52e1..5cf248a3a 100644
--- a/surfsense_web/messages/es.json
+++ b/surfsense_web/messages/es.json
@@ -394,7 +394,6 @@
 		"upload_error": "Error de subida",
 		"upload_error_desc": "Error al subir archivos",
 		"supported_file_types": "Tipos de archivo soportados",
-		"file_types_desc": "Estos tipos de archivo son soportados según la configuración actual de tu servicio ETL.",
 		"file_too_large": "Archivo demasiado grande",
 		"file_too_large_desc": "\"{name}\" excede el límite de {maxMB} MB por archivo.",
 		"no_supported_files_in_folder": "No se encontraron tipos de archivo compatibles en la carpeta seleccionada."
diff --git a/surfsense_web/messages/hi.json b/surfsense_web/messages/hi.json
index 9d4d982ad..0e7194832 100644
--- a/surfsense_web/messages/hi.json
+++ b/surfsense_web/messages/hi.json
@@ -394,7 +394,6 @@
 		"upload_error": "अपलोड त्रुटि",
 		"upload_error_desc": "फ़ाइलें अपलोड करने में त्रुटि",
 		"supported_file_types": "समर्थित फ़ाइल प्रकार",
-		"file_types_desc": "ये फ़ाइल प्रकार आपकी वर्तमान ETL सेवा कॉन्फ़िगरेशन के आधार पर समर्थित हैं।",
 		"file_too_large": "फ़ाइल बहुत बड़ी है",
 		"file_too_large_desc": "\"{name}\" प्रति फ़ाइल {maxMB}MB की सीमा से अधिक है।",
 		"no_supported_files_in_folder": "चयनित फ़ोल्डर में कोई समर्थित फ़ाइल प्रकार नहीं मिला।"
diff --git a/surfsense_web/messages/pt.json b/surfsense_web/messages/pt.json
index 7cb28d12f..00ae18eae 100644
--- a/surfsense_web/messages/pt.json
+++ b/surfsense_web/messages/pt.json
@@ -394,7 +394,6 @@
 		"upload_error": "Erro no envio",
 		"upload_error_desc": "Erro ao enviar arquivos",
 		"supported_file_types": "Tipos de arquivo suportados",
-		"file_types_desc": "Estes tipos de arquivo são suportados com base na configuração atual do seu serviço ETL.",
 		"file_too_large": "Arquivo muito grande",
 		"file_too_large_desc": "\"{name}\" excede o limite de {maxMB} MB por arquivo.",
 		"no_supported_files_in_folder": "Nenhum tipo de arquivo suportado encontrado na pasta selecionada."
diff --git a/surfsense_web/messages/zh.json b/surfsense_web/messages/zh.json
index 9d0108ebc..a6f3b5b84 100644
--- a/surfsense_web/messages/zh.json
+++ b/surfsense_web/messages/zh.json
@@ -378,7 +378,6 @@
 		"upload_error": "上传错误",
 		"upload_error_desc": "上传文件时出错",
 		"supported_file_types": "支持的文件类型",
-		"file_types_desc": "根据您当前的 ETL 服务配置支持这些文件类型。",
 		"file_too_large": "文件过大",
 		"file_too_large_desc": "\"{name}\" 超过了每个文件 {maxMB}MB 的限制。",
 		"no_supported_files_in_folder": "所选文件夹中没有找到支持的文件类型。"

From b759bb36a9694a8cd0820fbc8e1a65ba77bdec96 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 17:36:48 +0530
Subject: [PATCH 66/70] feat: add direct conversion support for CSV, TSV, and
 HTML files in local folder indexing

---
 .../local_folder_indexer.py                   |  26 ++-
 .../test_local_folder_pipeline.py             | 155 ++++++++++++++++++
 2 files changed, 175 insertions(+), 6 deletions(-)

diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index 539cfdd32..58c9f5003 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -49,8 +49,6 @@ PLAINTEXT_EXTENSIONS = frozenset(
         ".markdown",
         ".txt",
         ".text",
-        ".csv",
-        ".tsv",
         ".json",
         ".jsonl",
         ".yaml",
@@ -60,8 +58,6 @@ PLAINTEXT_EXTENSIONS = frozenset(
         ".cfg",
         ".conf",
         ".xml",
-        ".html",
-        ".htm",
         ".css",
         ".scss",
         ".less",
@@ -149,6 +145,9 @@ AUDIO_EXTENSIONS = frozenset(
 )
 
 
+DIRECT_CONVERT_EXTENSIONS = frozenset({".csv", ".tsv", ".html", ".htm"})
+
+
 def _is_plaintext_file(filename: str) -> bool:
     return Path(filename).suffix.lower() in PLAINTEXT_EXTENSIONS
 
@@ -157,9 +156,17 @@ def _is_audio_file(filename: str) -> bool:
     return Path(filename).suffix.lower() in AUDIO_EXTENSIONS
 
 
+def _is_direct_convert_file(filename: str) -> bool:
+    return Path(filename).suffix.lower() in DIRECT_CONVERT_EXTENSIONS
+
+
 def _needs_etl(filename: str) -> bool:
-    """File is not plaintext and not audio — requires ETL service to parse."""
-    return not _is_plaintext_file(filename) and not _is_audio_file(filename)
+    """File is not plaintext, not audio, and not direct-convert — requires ETL."""
+    return (
+        not _is_plaintext_file(filename)
+        and not _is_audio_file(filename)
+        and not _is_direct_convert_file(filename)
+    )
 
 
 HeartbeatCallbackType = Callable[[int], Awaitable[None]]
@@ -260,6 +267,13 @@ async def _read_file_content(file_path: str, filename: str) -> str:
     if _is_plaintext_file(filename):
         return _read_plaintext_file(file_path)
 
+    if _is_direct_convert_file(filename):
+        from app.tasks.document_processors._direct_converters import (
+            convert_file_directly,
+        )
+
+        return convert_file_directly(file_path, filename)
+
     if _is_audio_file(filename):
         etl_service = config.ETL_SERVICE if hasattr(config, "ETL_SERVICE") else None
         stt_service_val = config.STT_SERVICE if hasattr(config, "STT_SERVICE") else None
diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index 4062c3a3b..4c900bf51 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -804,3 +804,158 @@ class TestPipelineIntegration:
         )
         assert len(docs) == 1
         assert DocumentStatus.is_state(docs[0].status, DocumentStatus.READY)
+
+
+# ====================================================================
+# Tier 7: Direct Converters (DC1-DC4)
+# ====================================================================
+
+
+class TestDirectConvert:
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_dc1_csv_produces_markdown_table(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """DC1: CSV file is indexed as a markdown table, not raw comma-separated text."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "data.csv").write_text("name,age,city\nAlice,30,NYC\nBob,25,LA\n")
+
+        count, _skipped, _root_folder_id, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+        )
+
+        assert err is None
+        assert count == 1
+
+        doc = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
+                )
+            )
+        ).scalar_one()
+
+        assert "| name" in doc.source_markdown
+        assert "| Alice" in doc.source_markdown
+        assert "name,age,city" not in doc.source_markdown
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_dc2_tsv_produces_markdown_table(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """DC2: TSV file is indexed as a markdown table."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "data.tsv").write_text("name\tage\tcity\nAlice\t30\tNYC\nBob\t25\tLA\n")
+
+        count, _skipped, _root_folder_id, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+        )
+
+        assert err is None
+        assert count == 1
+
+        doc = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
+                )
+            )
+        ).scalar_one()
+
+        assert "| name" in doc.source_markdown
+        assert "| Alice" in doc.source_markdown
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_dc3_html_produces_clean_markdown(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """DC3: HTML file is indexed as clean markdown, not raw HTML."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "page.html").write_text(
+            "<h1>Title</h1><p>Hello world</p>"
+        )
+
+        count, _skipped, _root_folder_id, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+        )
+
+        assert err is None
+        assert count == 1
+
+        doc = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
+                )
+            )
+        ).scalar_one()
+
+        assert "Title" in doc.source_markdown
+        assert "<h1>" not in doc.source_markdown
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_dc4_csv_single_file_mode(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """DC4: CSV via single-file batch mode also produces a markdown table."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        (tmp_path / "data.csv").write_text("name,age,city\nAlice,30,NYC\nBob,25,LA\n")
+
+        count, _skipped, _root_folder_id, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            target_file_paths=[str(tmp_path / "data.csv")],
+        )
+
+        assert err is None
+        assert count == 1
+
+        doc = (
+            await db_session.execute(
+                select(Document).where(
+                    Document.document_type == DocumentType.LOCAL_FOLDER_FILE,
+                    Document.search_space_id == db_search_space.id,
+                )
+            )
+        ).scalar_one()
+
+        assert "| name" in doc.source_markdown
+        assert "name,age,city" not in doc.source_markdown

From edda5b98cb837eb16be2b33d9765c9532a656c10 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 17:38:29 +0530
Subject: [PATCH 67/70] chore: ran linting

---
 .../indexing_pipeline/test_local_folder_pipeline.py       | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index 4c900bf51..b94762ee6 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -860,7 +860,9 @@ class TestDirectConvert:
         """DC2: TSV file is indexed as a markdown table."""
         from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
 
-        (tmp_path / "data.tsv").write_text("name\tage\tcity\nAlice\t30\tNYC\nBob\t25\tLA\n")
+        (tmp_path / "data.tsv").write_text(
+            "name\tage\tcity\nAlice\t30\tNYC\nBob\t25\tLA\n"
+        )
 
         count, _skipped, _root_folder_id, err = await index_local_folder(
             session=db_session,
@@ -896,9 +898,7 @@ class TestDirectConvert:
         """DC3: HTML file is indexed as clean markdown, not raw HTML."""
         from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
 
-        (tmp_path / "page.html").write_text(
-            "<h1>Title</h1><p>Hello world</p>"
-        )
+        (tmp_path / "page.html").write_text("<h1>Title</h1><p>Hello world</p>")
 
         count, _skipped, _root_folder_id, err = await index_local_folder(
             session=db_session,

From 5068a6b4f392301a728f59f8c26fdf4679c6fc0c Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 17:52:59 +0530
Subject: [PATCH 68/70] style: update button variant and improve drag-and-drop
 UI in DocumentUploadTab

---
 .../components/sources/DocumentUploadTab.tsx  | 33 +++++++++++--------
 1 file changed, 20 insertions(+), 13 deletions(-)

diff --git a/surfsense_web/components/sources/DocumentUploadTab.tsx b/surfsense_web/components/sources/DocumentUploadTab.tsx
index 2d70a4e1a..0bf842b6d 100644
--- a/surfsense_web/components/sources/DocumentUploadTab.tsx
+++ b/surfsense_web/components/sources/DocumentUploadTab.tsx
@@ -401,15 +401,19 @@ export function DocumentUploadTab({
 			<DropdownMenu>
 				<DropdownMenuTrigger asChild onClick={(e) => e.stopPropagation()}>
 					<Button
-						variant="secondary"
+						variant="ghost"
 						size="sm"
-						className={`text-xs gap-1 ${sizeClass} ${widthClass}`}
+						className={`text-xs gap-1 bg-neutral-700/50 hover:bg-neutral-600/50 ${sizeClass} ${widthClass}`}
 					>
 						Browse
 						<ChevronDown className="h-3 w-3 opacity-60" />
 					</Button>
 				</DropdownMenuTrigger>
-				<DropdownMenuContent align="center" onClick={(e) => e.stopPropagation()}>
+				<DropdownMenuContent
+					align="center"
+					className="dark:bg-neutral-800"
+					onClick={(e) => e.stopPropagation()}
+				>
 					<DropdownMenuItem onClick={() => fileInputRef.current?.click()}>
 						<FileIcon className="h-4 w-4 mr-2" />
 						{t("browse_files")}
@@ -492,17 +496,20 @@ export function DocumentUploadTab({
 						</span>
 						{renderBrowseButton({ compact: true })}
 					</div>
-				) : isDragActive ? (
-					<div className="flex flex-col items-center gap-2">
-						<Upload className="h-8 w-8 text-primary" />
-						<p className="text-sm font-medium text-primary">{t("drop_files")}</p>
-					</div>
 				) : (
-					<div className="flex flex-col items-center gap-2">
-						<Upload className="h-8 w-8 text-muted-foreground" />
-						<p className="text-sm font-medium">{t("drag_drop")}</p>
-						<p className="text-xs text-muted-foreground">{t("file_size_limit")}</p>
-						<div className="mt-1">{renderBrowseButton()}</div>
+					<div className="relative">
+						{isDragActive && (
+							<div className="absolute inset-0 flex flex-col items-center justify-center gap-2">
+								<Upload className="h-8 w-8 text-primary" />
+								<p className="text-sm font-medium text-primary">{t("drop_files")}</p>
+							</div>
+						)}
+						<div className={`flex flex-col items-center gap-2 ${isDragActive ? "invisible" : ""}`}>
+							<Upload className="h-8 w-8 text-muted-foreground" />
+							<p className="text-sm font-medium">{t("drag_drop")}</p>
+							<p className="text-xs text-muted-foreground">{t("file_size_limit")}</p>
+							<div className="mt-1">{renderBrowseButton()}</div>
+						</div>
 					</div>
 				)}
 			</div>

From 414c4c86e9c64399c703b0a9ece6f9151a2e80da Mon Sep 17 00:00:00 2001
From: SohamBhattacharjee2003
 <125297948+SohamBhattacharjee2003@users.noreply.github.com>
Date: Fri, 3 Apr 2026 18:32:13 +0530
Subject: [PATCH 69/70] fix: add priority prop to Logo component for LCP
 optimization on auth pages

- Add optional priority prop to Logo component (defaults to false)
- Set priority=true on login and register pages to preload logo
- Logo on other pages remains lazy-loaded by default
- Improves LCP on critical auth pages by eliminating lazy-load delay
---
 surfsense_web/app/(home)/login/page.tsx    | 2 +-
 surfsense_web/app/(home)/register/page.tsx | 2 +-
 surfsense_web/components/Logo.tsx          | 3 +++
 3 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/surfsense_web/app/(home)/login/page.tsx b/surfsense_web/app/(home)/login/page.tsx
index 8b3be3805..09bf770d8 100644
--- a/surfsense_web/app/(home)/login/page.tsx
+++ b/surfsense_web/app/(home)/login/page.tsx
@@ -115,7 +115,7 @@ function LoginContent() {
 		<div className="relative w-full overflow-hidden">
 			<AmbientBackground />
 			<div className="mx-auto flex h-screen max-w-lg flex-col items-center justify-center">
-				<Logo className="h-16 w-16 md:h-32 md:w-32 rounded-md transition-all" />
+				<Logo priority className="h-16 w-16 md:h-32 md:w-32 rounded-md transition-all" />
 				<h1 className="mt-4 mb-6 text-xl font-bold text-neutral-800 dark:text-neutral-100 md:mt-8 md:mb-8 md:text-3xl lg:text-4xl transition-all">
 					{t("sign_in")}
 				</h1>
diff --git a/surfsense_web/app/(home)/register/page.tsx b/surfsense_web/app/(home)/register/page.tsx
index b9200c68f..2d590d7cc 100644
--- a/surfsense_web/app/(home)/register/page.tsx
+++ b/surfsense_web/app/(home)/register/page.tsx
@@ -160,7 +160,7 @@ export default function RegisterPage() {
 		<div className="relative w-full overflow-hidden">
 			<AmbientBackground />
 			<div className="mx-auto flex h-screen max-w-lg flex-col items-center justify-center px-6 md:px-0">
-				<Logo className="h-16 w-16 md:h-32 md:w-32 rounded-md transition-all" />
+				<Logo priority className="h-16 w-16 md:h-32 md:w-32 rounded-md transition-all" />
 				<h1 className="mt-4 mb-6 text-xl font-bold text-neutral-800 dark:text-neutral-100 md:mt-8 md:mb-8 md:text-3xl lg:text-4xl transition-all">
 					{t("create_account")}
 				</h1>
diff --git a/surfsense_web/components/Logo.tsx b/surfsense_web/components/Logo.tsx
index 121185757..0c1b2cce2 100644
--- a/surfsense_web/components/Logo.tsx
+++ b/surfsense_web/components/Logo.tsx
@@ -5,9 +5,11 @@ import { cn } from "@/lib/utils";
 export const Logo = ({
 	className,
 	disableLink = false,
+	priority = false,
 }: {
 	className?: string;
 	disableLink?: boolean;
+	priority?: boolean;
 }) => {
 	const image = (
 		<Image
@@ -16,6 +18,7 @@ export const Logo = ({
 			alt="logo"
 			width={128}
 			height={128}
+			priority={priority}
 		/>
 	);
 

From 9c0af6569d1e94744ad5361b9611efee0f57269c Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Fri, 3 Apr 2026 19:13:25 +0530
Subject: [PATCH 70/70] feat: implement page limit checks in local folder
 indexing to manage user page usage

---
 .../local_folder_indexer.py                   |  88 ++++++-
 .../test_local_folder_pipeline.py             | 219 ++++++++++++++++++
 2 files changed, 303 insertions(+), 4 deletions(-)

diff --git a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
index 58c9f5003..acfbce0bf 100644
--- a/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
+++ b/surfsense_backend/app/tasks/connector_indexers/local_folder_indexer.py
@@ -34,6 +34,7 @@ from app.indexing_pipeline.connector_document import ConnectorDocument
 from app.indexing_pipeline.document_hashing import compute_identifier_hash
 from app.indexing_pipeline.indexing_pipeline_service import IndexingPipelineService
 from app.services.llm_service import get_user_long_context_llm
+from app.services.page_limit_service import PageLimitExceededError, PageLimitService
 from app.services.task_logging_service import TaskLoggingService
 from app.tasks.celery_tasks import get_celery_session_maker
 from app.utils.document_versioning import create_version_snapshot
@@ -171,6 +172,39 @@ def _needs_etl(filename: str) -> bool:
 
 HeartbeatCallbackType = Callable[[int], Awaitable[None]]
 
+
+def _estimate_pages_safe(page_limit_service: PageLimitService, file_path: str) -> int:
+    """Estimate page count with a file-size fallback."""
+    try:
+        return page_limit_service.estimate_pages_before_processing(file_path)
+    except Exception:
+        file_size = os.path.getsize(file_path)
+        return max(1, file_size // (80 * 1024))
+
+
+async def _check_page_limit_or_skip(
+    page_limit_service: PageLimitService,
+    user_id: str,
+    file_path: str,
+) -> int:
+    """Estimate pages and check the limit; raises PageLimitExceededError if over quota.
+
+    Returns the estimated page count on success.
+    """
+    estimated = _estimate_pages_safe(page_limit_service, file_path)
+    await page_limit_service.check_page_limit(user_id, estimated)
+    return estimated
+
+
+def _compute_final_pages(
+    page_limit_service: PageLimitService,
+    estimated_pages: int,
+    content_length: int,
+) -> int:
+    """Return the final page count as max(estimated, actual)."""
+    actual = page_limit_service.estimate_pages_from_content_length(content_length)
+    return max(estimated_pages, actual)
+
 DEFAULT_EXCLUDE_PATTERNS = [
     ".git",
     "node_modules",
@@ -720,11 +754,12 @@ async def index_local_folder(
         skipped_count = 0
         failed_count = 0
 
+        page_limit_service = PageLimitService(session)
+
         # ================================================================
         # PHASE 1: Pre-filter files (mtime / content-hash), version changed
         # ================================================================
         connector_docs: list[ConnectorDocument] = []
-        # Maps unique_id -> (relative_path, mtime) for post-pipeline folder_id assignment
         file_meta_map: dict[str, dict] = {}
         seen_unique_hashes: set[str] = set()
 
@@ -759,6 +794,17 @@ async def index_local_folder(
                         skipped_count += 1
                         continue
 
+                    try:
+                        estimated_pages = await _check_page_limit_or_skip(
+                            page_limit_service, user_id, file_path_abs
+                        )
+                    except PageLimitExceededError:
+                        logger.warning(
+                            f"Page limit exceeded, skipping: {file_path_abs}"
+                        )
+                        failed_count += 1
+                        continue
+
                     try:
                         content, content_hash = await _compute_file_content_hash(
                             file_path_abs, file_info["relative_path"], search_space_id
@@ -781,6 +827,17 @@ async def index_local_folder(
 
                     await create_version_snapshot(session, existing_document)
                 else:
+                    try:
+                        estimated_pages = await _check_page_limit_or_skip(
+                            page_limit_service, user_id, file_path_abs
+                        )
+                    except PageLimitExceededError:
+                        logger.warning(
+                            f"Page limit exceeded, skipping: {file_path_abs}"
+                        )
+                        failed_count += 1
+                        continue
+
                     try:
                         content, content_hash = await _compute_file_content_hash(
                             file_path_abs, file_info["relative_path"], search_space_id
@@ -807,6 +864,8 @@ async def index_local_folder(
                 file_meta_map[unique_identifier] = {
                     "relative_path": relative_path,
                     "mtime": file_info["modified_at"].timestamp(),
+                    "estimated_pages": estimated_pages,
+                    "content_length": len(content),
                 }
 
             except Exception as e:
@@ -901,6 +960,15 @@ async def index_local_folder(
                     doc_meta = dict(result.document_metadata or {})
                     doc_meta["mtime"] = mtime_info.get("mtime")
                     result.document_metadata = doc_meta
+
+                    est = mtime_info.get("estimated_pages", 1)
+                    content_len = mtime_info.get("content_length", 0)
+                    final_pages = _compute_final_pages(
+                        page_limit_service, est, content_len
+                    )
+                    await page_limit_service.update_page_usage(
+                        user_id, final_pages, allow_exceed=True
+                    )
                 else:
                     failed_count += 1
 
@@ -1084,6 +1152,14 @@ async def _index_single_file(
             DocumentType.LOCAL_FOLDER_FILE.value, unique_id, search_space_id
         )
 
+        page_limit_service = PageLimitService(session)
+        try:
+            estimated_pages = await _check_page_limit_or_skip(
+                page_limit_service, user_id, str(full_path)
+            )
+        except PageLimitExceededError as e:
+            return 0, 1, f"Page limit exceeded: {e}"
+
         try:
             content, content_hash = await _compute_file_content_hash(
                 str(full_path), full_path.name, search_space_id
@@ -1128,8 +1204,6 @@ async def _index_single_file(
 
         db_doc = documents[0]
 
-        # Assign folder_id before indexing so the doc appears in the
-        # correct folder while still pending/processing.
         if root_folder_id:
             try:
                 db_doc.folder_id = await _resolve_folder_for_file(
@@ -1154,10 +1228,16 @@ async def _index_single_file(
         failed_msg = None if indexed else "Indexing failed"
 
         if indexed:
+            final_pages = _compute_final_pages(
+                page_limit_service, estimated_pages, len(content)
+            )
+            await page_limit_service.update_page_usage(
+                user_id, final_pages, allow_exceed=True
+            )
             await task_logger.log_task_success(
                 log_entry,
                 f"Single file indexed: {rel_path}",
-                {"file": rel_path},
+                {"file": rel_path, "pages_processed": final_pages},
             )
         return indexed, 0 if indexed else 1, failed_msg
 
diff --git a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
index b94762ee6..4d9bda7ee 100644
--- a/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
+++ b/surfsense_backend/tests/integration/indexing_pipeline/test_local_folder_pipeline.py
@@ -959,3 +959,222 @@ class TestDirectConvert:
 
         assert "| name" in doc.source_markdown
         assert "name,age,city" not in doc.source_markdown
+
+
+# ====================================================================
+# Tier 8: Page Limits (PL1-PL6)
+# ====================================================================
+
+
+class TestPageLimits:
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_pl1_full_scan_increments_pages_used(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """PL1: Successful full-scan sync increments user.pages_used."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        db_user.pages_used = 0
+        db_user.pages_limit = 500
+        await db_session.flush()
+
+        (tmp_path / "note.md").write_text("# Hello World\n\nContent here.")
+
+        count, _skipped, _root_folder_id, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+        )
+
+        assert err is None
+        assert count == 1
+
+        await db_session.refresh(db_user)
+        assert db_user.pages_used > 0, "pages_used should increase after indexing"
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_pl2_full_scan_blocked_when_limit_exhausted(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """PL2: Full-scan skips file when page limit is exhausted."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        db_user.pages_used = 100
+        db_user.pages_limit = 100
+        await db_session.flush()
+
+        (tmp_path / "note.md").write_text("# Hello World\n\nContent here.")
+
+        count, _skipped, _root_folder_id, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+        )
+
+        assert count == 0
+
+        await db_session.refresh(db_user)
+        assert db_user.pages_used == 100, "pages_used should not change on rejection"
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_pl3_single_file_increments_pages_used(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """PL3: Single-file mode increments user.pages_used on success."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        db_user.pages_used = 0
+        db_user.pages_limit = 500
+        await db_session.flush()
+
+        (tmp_path / "note.md").write_text("# Hello World\n\nContent here.")
+
+        count, _skipped, _root_folder_id, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            target_file_paths=[str(tmp_path / "note.md")],
+        )
+
+        assert err is None
+        assert count == 1
+
+        await db_session.refresh(db_user)
+        assert db_user.pages_used > 0, "pages_used should increase after indexing"
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_pl4_single_file_blocked_when_limit_exhausted(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """PL4: Single-file mode skips file when page limit is exhausted."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        db_user.pages_used = 100
+        db_user.pages_limit = 100
+        await db_session.flush()
+
+        (tmp_path / "note.md").write_text("# Hello World\n\nContent here.")
+
+        count, _skipped, _root_folder_id, err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            target_file_paths=[str(tmp_path / "note.md")],
+        )
+
+        assert count == 0
+        assert err is not None
+        assert "page limit" in err.lower()
+
+        await db_session.refresh(db_user)
+        assert db_user.pages_used == 100, "pages_used should not change on rejection"
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_pl5_unchanged_resync_no_extra_pages(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+    ):
+        """PL5: Re-syncing an unchanged file does not consume additional pages."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        db_user.pages_used = 0
+        db_user.pages_limit = 500
+        await db_session.flush()
+
+        (tmp_path / "note.md").write_text("# Hello\n\nSame content.")
+
+        count1, _, root_folder_id, _ = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+        )
+        assert count1 == 1
+
+        await db_session.refresh(db_user)
+        pages_after_first = db_user.pages_used
+        assert pages_after_first > 0
+
+        count2, _, _, _ = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            root_folder_id=root_folder_id,
+        )
+        assert count2 == 0
+
+        await db_session.refresh(db_user)
+        assert db_user.pages_used == pages_after_first, (
+            "pages_used should not increase for unchanged files"
+        )
+
+    @pytest.mark.usefixtures(*UNIFIED_FIXTURES)
+    async def test_pl6_batch_partial_page_limit_exhaustion(
+        self,
+        db_session: AsyncSession,
+        db_user: User,
+        db_search_space: SearchSpace,
+        tmp_path: Path,
+        patched_batch_sessions,
+    ):
+        """PL6: Batch mode with a very low page limit: some files succeed, rest fail."""
+        from app.tasks.connector_indexers.local_folder_indexer import index_local_folder
+
+        db_user.pages_used = 0
+        db_user.pages_limit = 1
+        await db_session.flush()
+
+        (tmp_path / "a.md").write_text("File A content")
+        (tmp_path / "b.md").write_text("File B content")
+        (tmp_path / "c.md").write_text("File C content")
+
+        count, failed, _root_folder_id, _err = await index_local_folder(
+            session=db_session,
+            search_space_id=db_search_space.id,
+            user_id=str(db_user.id),
+            folder_path=str(tmp_path),
+            folder_name="test-folder",
+            target_file_paths=[
+                str(tmp_path / "a.md"),
+                str(tmp_path / "b.md"),
+                str(tmp_path / "c.md"),
+            ],
+        )
+
+        assert count >= 1, "at least one file should succeed"
+        assert failed >= 1, "at least one file should fail due to page limit"
+        assert count + failed == 3
+
+        await db_session.refresh(db_user)
+        assert db_user.pages_used > 0
+        assert db_user.pages_used <= db_user.pages_limit + 1