docs(TSP-1102): expand project files section to cover folder @mentions

get-started/chat/introduction.mdx

@@ -13,12 +13,12 @@
   Start chatting now at chat.relevanceai.com — works on desktop and mobile
 </Card>
 
 ## Using different LLMs in Chat
 
 You can select the LLM you want to use in Chat:
 
 <div style={{ width:"100%",position:"relative","padding-top":"56.75%"}}>
 <iframe src="https://app.supademo.com/embed/cmfgfi5x0bz4239ozw2fj4het" frameBorder="0" title="How to set up Google Drive as a source of Knowledge" allow="clipboard-write; fullscreen" webkitAllowFullscreen="true" mozAllowFullscreen="true" allowFullscreen style={{ position:"absolute",top:0,left:0,width:"100%",height:"100%",border:"3px solid #5E43CE",borderRadius:"10px" }} />
 </div>
 
 1. Click the name of the LLM you're currently on (or Auto if you've selected 'Auto' previously) in the top right of Chat
@@ -101,7 +101,7 @@
 Save any prompt from your Chat conversations to make it available to all users in your project through the @ menu.
 
 <div style={{ width:"100%",position:"relative","padding-top":"56.75%" }}>
 <iframe src="https://app.supademo.com/embed/cminu37g60bizgxadmuzniah7" frameBorder="0" title="How to save a prompt" allow="clipboard-write; fullscreen" webkitAllowFullscreen="true" mozAllowFullscreen="true" allowFullscreen style={{ position:"absolute",top:0,left:0,width:"100%",height:"100%",border:"3px solid #5E43CE",borderRadius:"10px" }} />
 </div>
 
 1. Start a new conversation and enter the prompt you want to save
@@ -138,15 +138,48 @@
 
 ---
 
-## Project files
+## Project files and folders
 
-You can search and insert files from your project's file system directly in Chat using the @ menu. Files appear alongside agents, workforces, and saved prompts in results, showing the file icon, name, and path.
+You can reference files and folders from your project's connected storage directly in Chat using the @ menu. When you @mention a file or folder, its contents are included in the context sent to the agent — so you can ask questions about documents, analyze data, or run tasks against file content without manually uploading anything.
 
-### Searching for project files
+<Info>
+Project file and folder @mentions work with files stored in connected storage integrations (such as Google Drive). They are distinct from file attachments (uploading a file directly into the chat) and knowledge sources (files indexed for retrieval by agents).
+</Info>
+
+### Referencing individual files
+
+1. Type `@` in the chat input field to open the menu
+2. Start typing the file name — files appear in the results alongside agents and saved prompts, showing the file name and its path
+3. Select a file to insert a reference into your message
+4. Add your question or instruction alongside the reference and send
+
+The file's contents are fetched and included in the context when your message is sent.
+
+### Referencing entire folders
+
+Referencing a folder includes all files within that folder in the context of your message — useful when you want an agent to work across a set of related documents without referencing each one individually.
+
+1. Type `@` in the chat input field to open the menu
+2. Start typing the folder name — folders appear in the results alongside files, agents, and saved prompts
+3. Select a folder to insert a reference into your message
+4. Add your question or instruction and send
 
-1. **Type @** in the chat input field followed by a search query
-2. Browse the results — files appear alongside agents, workforces, and saved prompts, showing the file name and path
-3. Select a file to insert its file path into your message
+<Warning>
+Referencing large folders with many files will consume more context. If you hit limits, reference specific files instead of the whole folder.
+</Warning>
+
+### When to use file and folder references
+
+| Approach | Best for |
+|----------|----------|
+| **@ mention a file** | Asking questions about a specific document, analyzing a single file |
+| **@ mention a folder** | Working across a set of related files, summarizing a project directory |
+| **File attachment** | Uploading a file you have locally that isn't in connected storage |
+| **Knowledge source** | Giving an agent persistent, searchable access to a large document library |
+
+<Tip>
+Combine file @mentions with agent @mentions in the same message — for example, `@ResearchAgent summarize @quarterly-report.pdf` — to direct a specific agent at a specific file.
+</Tip>
 
 ---
 
@@ -196,7 +229,7 @@
 
 ## Supported file types in Chat
 
 Chat empowers you to work with a wide range of file types, both for input and output. Upload documents, images, and data files to provide context to your conversations, and generate new files based on your Agent's responses or built-in Agent outputs. Whether you're analyzing spreadsheets, processing PDFs, or creating presentations, Chat seamlessly handles file operations across different model providers.
 
 Here's a comprehensive breakdown of supported file types by model provider:
 
@@ -330,7 +363,7 @@
         To monitor your Chat credit usage, navigate to **Settings > Plan & Billing** to see a detailed breakdown of your credit expenses. Learn more about [Plans and credits](/admin/subscriptions/plans).
         </Tip>
     </Accordion>
     <Accordion title="Can I use different LLMs in Chat?">
     Yes, you can select the LLM you want to use in Chat by following these steps:
 
     1. Click on the cog icon in the top right of your screen