feat(copilot): mount the docs corpus in the VFS with path-scoped search_docs

.github/workflows/test-build.yml

@@ -123,6 +123,9 @@ jobs:
       - name: Repo audits
         run: bun run check:audits
 
+      - name: Verify docs manifest is in sync
+        run: bun run docs-manifest:check
+
       - name: Migration safety (zero-downtime) audit
         run: |
           if [ "${{ github.event_name }}" = "pull_request" ]; then

apps/sim/app/api/mothership/execute/route.test.ts

@@ -237,8 +237,13 @@ describe('mothership private trace provenance transport', () => {
       'user-1',
       'secret-value __var_FOREIGN',
       'workspace-1',
-      'chat-1'
+      'chat-1',
+      expect.any(Object)
     )
+
+    const contextRegistry = mockProcessContextsServer.mock.calls.at(-1)?.[5]
+    const lifecycleOptions = mockRunHeadlessCopilotLifecycle.mock.calls.at(-1)?.[1]
+    expect(contextRegistry).toBe(lifecycleOptions.environmentContext?.resolvedSecretTraceRegistry)
   })
 
   it('keeps context routing and display inputs raw until the lifecycle boundary', async () => {
@@ -290,7 +295,8 @@ describe('mothership private trace provenance transport', () => {
       'user-1',
       'hello',
       'workspace-1',
-      'chat-1'
+      'chat-1',
+      expect.any(Object)
     )
   })
 

apps/sim/app/api/mothership/execute/route.ts

@@ -244,7 +244,8 @@ export const POST = withRouteHandler(async (req: NextRequest) => {
           userId,
           lastUserMessage,
           workspaceId,
-          effectiveChatId
+          effectiveChatId,
+          activeResolvedSecretTraceRegistry
         ).catch((error) => {
           reqLogger.warn('Failed to resolve agent contexts for execution', {
             error: toError(error).message,

apps/sim/lib/copilot/chat/post.test.ts

@@ -384,7 +384,8 @@ describe('handleUnifiedChatPost', () => {
       'user-1',
       'Hello',
       'ws-1',
-      expect.anything()
+      expect.anything(),
+      expect.any(ResolvedSecretTraceRegistry)
     )
   })
 
@@ -448,7 +449,8 @@ describe('handleUnifiedChatPost', () => {
       'user-1',
       'Explain these selections',
       'ws-1',
-      'chat-1'
+      'chat-1',
+      expect.any(ResolvedSecretTraceRegistry)
     )
   })
 

apps/sim/lib/copilot/chat/post.ts

@@ -461,9 +461,19 @@ async function resolveAgentContexts(params: {
   message: string
   workspaceId?: string
   chatId?: string
+  resolvedSecretTraceRegistry?: ExecutionContext['resolvedSecretTraceRegistry']
   requestId: string
 }): Promise<Array<{ type: string; content: string; tag?: string; path?: string }>> {
-  const { contexts, resourceAttachments, userId, message, workspaceId, chatId, requestId } = params
+  const {
+    contexts,
+    resourceAttachments,
+    userId,
+    message,
+    workspaceId,
+    chatId,
+    resolvedSecretTraceRegistry,
+    requestId,
+  } = params
 
   let agentContexts: Array<{ type: string; content: string; tag?: string; path?: string }> = []
 
@@ -474,7 +484,8 @@ async function resolveAgentContexts(params: {
         userId,
         message,
         workspaceId,
-        chatId
+        chatId,
+        resolvedSecretTraceRegistry
       )
     } catch (error) {
       logger.error(`[${requestId}] Failed to process contexts`, error)
@@ -1267,7 +1278,7 @@ export async function handleUnifiedChatPost(req: NextRequest) {
           }),
         activeOtelRoot.context
       )
-      const agentContextsPromise = executionContextPromise.then(() => {
+      const agentContextsPromise = executionContextPromise.then((executionContext) => {
         return withCopilotSpan(
           TraceSpan.CopilotChatResolveAgentContexts,
           {
@@ -1282,6 +1293,7 @@ export async function handleUnifiedChatPost(req: NextRequest) {
               message: body.message,
               workspaceId,
               chatId: actualChatId,
+              resolvedSecretTraceRegistry: executionContext.resolvedSecretTraceRegistry,
               requestId,
             }),
           activeOtelRoot.context

apps/sim/lib/copilot/chat/process-contents.test.ts

@@ -10,6 +10,7 @@ import {
   MAX_TABLE_SELECTION_ROWS,
 } from '@/lib/copilot/chat/selection-context'
 import { DelegatedWorkspaceAuthorizationError } from '@/lib/core/application'
+import { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secret-trace-registry'
 import type { ChatContext } from '@/stores/panel'
 
 const {
@@ -25,6 +26,7 @@ const {
   readKnowledgeBase,
   getBlockVisibilityForCopilot,
   isIntegrationDeploymentAvailable,
+  searchDocsExecute,
 } = vi.hoisted(() => ({
   discoverServerTools: vi.fn(),
   getBlock: vi.fn(),
@@ -38,6 +40,7 @@ const {
   readKnowledgeBase: vi.fn(),
   getBlockVisibilityForCopilot: vi.fn(async () => null),
   isIntegrationDeploymentAvailable: vi.fn(() => true),
+  searchDocsExecute: vi.fn(),
 }))
 
 vi.mock('@/blocks/registry', () => ({ getBlock, getBlockRegistry }))
@@ -57,6 +60,9 @@ vi.mock('@/lib/table/rows/service', () => ({ getRowsByIds }))
 vi.mock('@/lib/knowledge/application/knowledge-bases', () => ({
   readKnowledgeBase: { execute: readKnowledgeBase },
 }))
+vi.mock('@/lib/copilot/tools/server/docs/search-docs', () => ({
+  searchDocsServerTool: { execute: searchDocsExecute },
+}))
 
 /**
  * Overrides the global `@sim/db` mock: the logs-context tests below need
@@ -282,6 +288,121 @@ describe('processContextsServer - skill contexts', () => {
   })
 })
 
+describe('processContextsServer - docs contexts', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('routes @Docs to an unscoped search_docs query', async () => {
+    const resolvedSecretTraceRegistry = new ResolvedSecretTraceRegistry()
+    const results = [
+      {
+        path: 'docs/workflows/loops.mdx',
+        url: 'https://docs.sim.ai/workflows/loops',
+        title: 'Loops',
+        content: 'Use a loop block to iterate.',
+        similarity: 0.9,
+      },
+    ]
+    searchDocsExecute.mockResolvedValue({ results, query: 'how do loops work?', totalResults: 1 })
+
+    const result = await processContextsServer(
+      [{ kind: 'docs', label: 'Docs' }],
+      'user-1',
+      '@Docs how do loops work?',
+      'ws-1',
+      undefined,
+      resolvedSecretTraceRegistry
+    )
+
+    expect(searchDocsExecute).toHaveBeenCalledWith(
+      { query: 'how do loops work?' },
+      {
+        userId: 'user-1',
+        workspaceId: 'ws-1',
+        chatId: undefined,
+        resolvedSecretTraceRegistry,
+      }
+    )
+    expect(result).toEqual([
+      {
+        type: 'docs',
+        tag: '@Docs',
+        content: JSON.stringify({ results }),
+      },
+    ])
+  })
+
+  it('preserves the search note when @Docs has no relevant matches', async () => {
+    const note =
+      'No relevant matches. This does NOT mean the docs lack this topic. Rephrase the query.'
+    searchDocsExecute.mockResolvedValue({ results: [], query: 'new topic', totalResults: 0, note })
+
+    const result = await processContextsServer(
+      [{ kind: 'docs', label: 'Docs' }],
+      'user-1',
+      '@Docs new topic',
+      'ws-1',
+      undefined,
+      new ResolvedSecretTraceRegistry()
+    )
+
+    expect(result).toEqual([
+      {
+        type: 'docs',
+        tag: '@Docs',
+        content: JSON.stringify({ results: [], note }),
+      },
+    ])
+  })
+
+  it('uses the Docs label when the message only contains the mention', async () => {
+    searchDocsExecute.mockResolvedValue({ results: [], query: 'Docs', totalResults: 0 })
+
+    await processContextsServer(
+      [{ kind: 'docs', label: 'Docs' }],
+      'user-1',
+      '@Docs',
+      'ws-1',
+      'chat-1',
+      new ResolvedSecretTraceRegistry()
+    )
+
+    expect(searchDocsExecute).toHaveBeenCalledWith(
+      { query: 'Docs' },
+      expect.objectContaining({ workspaceId: 'ws-1', chatId: 'chat-1' })
+    )
+  })
+
+  it('preserves an explicit unavailable note when docs search fails', async () => {
+    searchDocsExecute.mockRejectedValue(new Error('embedding service unavailable'))
+
+    const result = await processContextsServer(
+      [{ kind: 'docs', label: 'Docs' }],
+      'user-1',
+      '@Docs explain schedules',
+      'ws-1',
+      'chat-1',
+      new ResolvedSecretTraceRegistry()
+    )
+
+    expect(result).toEqual([
+      {
+        type: 'docs',
+        tag: '@Docs',
+        content: JSON.stringify({
+          results: [],
+          note: 'Documentation search is temporarily unavailable. Do not infer that the docs lack this topic; retry search_docs or browse docs/** later.',
+        }),
+      },
+    ])
+    expect(mockProcessContentsLogger.error).toHaveBeenCalledWith(
+      'Failed to process docs context',
+      expect.any(Error)
+    )
+  })
+})
+
 describe('processContextsServer - MCP contexts', () => {
   beforeEach(() => {
     vi.clearAllMocks()

apps/sim/lib/copilot/chat/process-contents.ts

@@ -49,6 +49,7 @@ import { readWorkspaceFileMetadata } from '@/lib/workspace-files/application/rea
 import { parseWorkspaceFileFolderDisplayPath } from '@/lib/workspace-files/folder-display-path'
 import { getUserPermissionConfig } from '@/ee/access-control/utils/permission-check'
 import { escapeRegExp } from '@/executor/constants'
+import type { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secret-trace-registry'
 import type { BrowserTextSelection, ChatContext, TerminalTextSelection } from '@/stores/panel'
 
 type AgentContextType =
@@ -124,7 +125,8 @@ export async function processContextsServer(
   userId: string,
   userMessage?: string,
   currentWorkspaceId?: string,
-  chatId?: string
+  chatId?: string,
+  resolvedSecretTraceRegistry?: ResolvedSecretTraceRegistry
 ): Promise<AgentContext[]> {
   if (!Array.isArray(contexts) || contexts.length === 0) return []
   const tasks = contexts.map(async (ctx) => {
@@ -314,17 +316,36 @@ export async function processContextsServer(
       }
       if (ctx.kind === 'docs') {
         try {
-          const { searchDocumentationServerTool } = await import(
-            '@/lib/copilot/tools/server/docs/search-documentation'
+          const { searchDocsServerTool } = await import(
+            '@/lib/copilot/tools/server/docs/search-docs'
           )
           const rawQuery = (userMessage || '').trim() || ctx.label || 'Sim documentation'
-          const query = sanitizeMessageForDocs(rawQuery, contexts)
-          const res = await searchDocumentationServerTool.execute({ query, topK: 10 })
-          const content = JSON.stringify(res?.results || [])
+          const query =
+            sanitizeMessageForDocs(rawQuery, contexts) || ctx.label || 'Sim documentation'
+          const res = await searchDocsServerTool.execute(
+            { query },
+            {
+              userId,
+              workspaceId: currentWorkspaceId,
+              chatId,
+              resolvedSecretTraceRegistry,
+            }
+          )
+          const content = JSON.stringify({
+            results: res?.results || [],
+            ...(res?.note ? { note: res.note } : {}),
+          })
           return { type: 'docs', tag: ctx.label ? `@${ctx.label}` : '@', content }
         } catch (e) {
           logger.error('Failed to process docs context', e)
-          return null
+          return {
+            type: 'docs',
+            tag: ctx.label ? `@${ctx.label}` : '@',
+            content: JSON.stringify({
+              results: [],
+              note: 'Documentation search is temporarily unavailable. Do not infer that the docs lack this topic; retry search_docs or browse docs/** later.',
+            }),
+          }
         }
       }
       return null