fix(search): harden connector recovery and file lifecycle

Author: waleedlatif1

apps/docs/content/docs/search/github.mdx

@@ -11,7 +11,7 @@ GitHub Search indexes text files from a repository on `github.com`. A workspace
 
 ## Before you start
 
-Your Sim deployment needs a GitHub App configured as described below. For private repositories, an owner or administrator must install that App on them. Each person needs a verified GitHub email address matching their Sim account; the address can be private or secondary.
+Your Sim deployment needs a GitHub App configured as described below. The repository must contain at least one commit; initialize an empty repository with a README before adding it. For private repositories, an owner or administrator must install that App on them. Each person needs a verified GitHub email address matching their Sim account; the address can be private or secondary.
 
 ## Configure the GitHub App
 
@@ -144,7 +144,8 @@ With **Connected members**, indexing begins after someone connects. A dedicated
 | Identity verification fails | Verify the email used by your Sim account in GitHub's email settings, then reconnect. A public profile email alone is insufficient. |
 | Authorization fails after installation | Return to Sim and start **Connect account** there. Do not enable authorization during installation. |
 | Sync is incomplete | Review the source status. Very large Git trees, file size limits, and unreadable files can limit indexing. |
+| Empty repository returns an error | Add an initial commit, then sync again. GitHub does not return a file tree for an uninitialized repository. |
 
 <Callout type="info">
-  GitHub Search currently covers repository text files. Issues, pull requests, separate wikis, GitHub Enterprise Server, and `ghe.com` domains are not supported by this connector. Personal access tokens remain available for general knowledge-base connectors, with that knowledge base's access rules.
+  GitHub Search covers repository text files up to 100 MB, including symbolic links to files within the same repository. Path and extension filters apply to the link's path. Broken or external links, binaries, and submodules are not indexed. Issues, pull requests, separate wikis, GitHub Enterprise Server, and `ghe.com` domains are not supported by this connector. Personal access tokens remain available for general knowledge-base connectors, with that knowledge base's access rules.
 </Callout>

apps/sim/app/workspace/[workspaceId]/knowledge/[id]/base.tsx

@@ -589,9 +589,6 @@ export function KnowledgeBase({
     )
   }
 
-  /**
-   * Handles retrying a failed document processing
-   */
   const handleRetryDocument = (docId: string) => {
     updateDocument(docId, {
       processingStatus: 'pending',
@@ -1255,7 +1252,7 @@ export function KnowledgeBase({
                 </span>
               ),
             },
-            size: { label: formatFileSize(doc.fileSize) },
+            size: { label: formatFileSize(doc.fileSize, { includeBytes: true }) },
             tokens: {
               label:
                 doc.processingStatus === 'completed'
@@ -1551,6 +1548,13 @@ export function KnowledgeBase({
             ? () => handleViewDocumentTags(contextMenuDocument)
             : undefined
         }
+        onRetry={
+          contextMenuDocument?.processingStatus === 'failed' &&
+          selectedDocumentCount === 1 &&
+          userPermissions.canEdit
+            ? () => handleRetryDocument(contextMenuDocument.id)
+            : undefined
+        }
         onDelete={
           contextMenuDocument
             ? selectedDocumentCount > 1

apps/sim/app/workspace/[workspaceId]/knowledge/[id]/components/document-context-menu/document-context-menu.test.tsx

@@ -0,0 +1,82 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { DocumentContextMenu } from '@/app/workspace/[workspaceId]/knowledge/[id]/components/document-context-menu/document-context-menu'
+
+class ResizeObserverMock {
+  observe = vi.fn()
+  unobserve = vi.fn()
+  disconnect = vi.fn()
+}
+
+let container: HTMLDivElement
+let root: Root
+
+beforeEach(() => {
+  vi.stubGlobal('ResizeObserver', ResizeObserverMock)
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  vi.unstubAllGlobals()
+})
+
+describe('DocumentContextMenu retry', () => {
+  it('offers an accessible Retry action and invokes the provided handler on selection', () => {
+    const onRetry = vi.fn()
+    const onClose = vi.fn()
+
+    act(() => {
+      root.render(
+        <DocumentContextMenu
+          isOpen
+          position={{ x: 0, y: 0 }}
+          onClose={onClose}
+          hasDocument
+          selectedCount={1}
+          onRetry={onRetry}
+        />
+      )
+    })
+
+    const item = document.body.querySelector<HTMLElement>('[role="menuitem"]')
+    expect(item).toHaveAccessibleName('Retry')
+    expect(item).not.toHaveAttribute('aria-disabled', 'true')
+
+    act(() => item?.click())
+
+    expect(onRetry).toHaveBeenCalledOnce()
+    expect(onClose).toHaveBeenCalledOnce()
+  })
+
+  it.each([
+    { scenario: 'no retry handler', selectedCount: 1, hasDocument: true, canRetry: false },
+    { scenario: 'multiple documents', selectedCount: 2, hasDocument: true, canRetry: true },
+    { scenario: 'empty space', selectedCount: 0, hasDocument: false, canRetry: true },
+  ])('does not offer Retry for $scenario', ({ selectedCount, hasDocument, canRetry }) => {
+    const onRetry = vi.fn()
+
+    act(() => {
+      root.render(
+        <DocumentContextMenu
+          isOpen
+          position={{ x: 0, y: 0 }}
+          onClose={vi.fn()}
+          hasDocument={hasDocument}
+          selectedCount={selectedCount}
+          onRetry={canRetry ? onRetry : undefined}
+        />
+      )
+    })
+
+    expect(document.body.querySelector('[role="menuitem"]')).toBeNull()
+    expect(onRetry).not.toHaveBeenCalled()
+  })
+})

apps/sim/app/workspace/[workspaceId]/knowledge/[id]/components/document-context-menu/document-context-menu.tsx

@@ -7,7 +7,7 @@ import {
   DropdownMenuSeparator,
   DropdownMenuTrigger,
 } from '@sim/emcn'
-import { Eye, Pencil, Plus, SquareArrowUpRight, TagIcon, Trash } from '@sim/emcn/icons'
+import { Eye, Pencil, Plus, RefreshCw, SquareArrowUpRight, TagIcon, Trash } from '@sim/emcn/icons'
 import {
   selectionActionLabel,
   selectionToggleActionLabel,
@@ -22,6 +22,7 @@ interface DocumentContextMenuProps {
   onRename?: () => void
   onToggleEnabled?: () => void
   onViewTags?: () => void
+  onRetry?: () => void
   onDelete?: () => void
   onAddDocument?: () => void
   isDocumentEnabled?: boolean
@@ -50,6 +51,7 @@ export function DocumentContextMenu({
   onRename,
   onToggleEnabled,
   onViewTags,
+  onRetry,
   onDelete,
   onAddDocument,
   isDocumentEnabled = true,
@@ -74,7 +76,7 @@ export function DocumentContextMenu({
 
   const hasNavigationSection = !isMultiSelect && (!!onOpenInNewTab || !!onOpenSource)
   const hasEditSection = !isMultiSelect && (!!onRename || !!onViewTags)
-  const hasStateSection = !!onToggleEnabled
+  const hasStateSection = !!onToggleEnabled || (!isMultiSelect && !!onRetry)
   const hasDestructiveSection = !!onDelete
   const hasActionsAboveDestructive = hasNavigationSection || hasEditSection || hasStateSection
 
@@ -132,6 +134,12 @@ export function DocumentContextMenu({
                 {toggleLabel}
               </DropdownMenuItem>
             )}
+            {!isMultiSelect && onRetry && (
+              <DropdownMenuItem onSelect={onRetry}>
+                <RefreshCw />
+                Retry
+              </DropdownMenuItem>
+            )}
 
             {hasActionsAboveDestructive && hasDestructiveSection && <DropdownMenuSeparator />}
             {onDelete && (