diff --git a/docs.json b/docs.json
index 6c23cead..a6ad21eb 100644
--- a/docs.json
+++ b/docs.json
@@ -38,6 +38,7 @@
             "group": "Chat",
             "pages": [
               "get-started/chat/introduction",
+              "get-started/chat/project-files",
               {
                 "group": "Chat Agents",
                 "pages": [
diff --git a/get-started/chat/introduction.mdx b/get-started/chat/introduction.mdx
index ddcda282..f05d3b01 100644
--- a/get-started/chat/introduction.mdx
+++ b/get-started/chat/introduction.mdx
@@ -148,6 +148,8 @@ You can search and insert files from your project's file system directly in Chat
 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
 
+For a full guide to browsing and managing project files — including view options, folder navigation, and file operations — see [Project files](/get-started/chat/project-files).
+
 ---
 
 ## Providing Feedback on Responses
diff --git a/get-started/chat/project-files.mdx b/get-started/chat/project-files.mdx
new file mode 100644
index 00000000..e3dbd269
--- /dev/null
+++ b/get-started/chat/project-files.mdx
@@ -0,0 +1,72 @@
+---
+title: "Project files"
+sidebarTitle: "Project files"
+description: "Browse and manage files in your project's file system from the Chat interface"
+---
+
+The filesystem browser in Chat gives you a visual way to explore and manage files stored in your project. You can view folder hierarchies, perform file operations, and reference files directly in your chat messages using @.
+
+## Accessing the filesystem browser
+
+The filesystem browser appears in the right sidebar panel of Chat. To open it, select the **Files** tab in the SuperAgent panel on the right side of the Chat interface.
+
+---
+
+## View options
+
+The filesystem browser supports two layout modes so you can work in whichever format suits your task.
+
+### List view
+
+The default layout displays files and folders in a hierarchical tree structure. This view is useful for navigating deeply nested directories and seeing the full folder structure at a glance.
+
+### Grid view
+
+Grid view displays files as icon tiles in a Finder-style layout. Each tile shows the file icon and name, making it easier to visually scan a flat directory with many files.
+
+### Switching between views
+
+Use the toggle button in the filesystem browser toolbar to switch between list view and grid view. Your view choice is saved automatically and persists across sessions — the next time you open Chat, the filesystem browser will use the same layout you last selected.
+
+---
+
+## Navigating folders
+
+A breadcrumb trail at the top of the filesystem browser shows your current location in the folder hierarchy. Click any folder name in the breadcrumb to jump directly to that level.
+
+---
+
+## File operations
+
+Right-clicking a file or folder in either view opens a context menu with the following operations:
+
+| Operation | Description |
+|-----------|-------------|
+| **Open** | Opens the file for viewing |
+| **Download** | Downloads the file to your local machine |
+| **Copy file path** | Copies the full path of the file to your clipboard |
+| **Rename** | Renames the file or folder inline |
+| **Delete** | Permanently deletes the file or folder |
+
+<Warning>
+Delete operations are permanent and cannot be undone.
+</Warning>
+
+---
+
+## Referencing files in chat
+
+Files visible in the filesystem browser can be referenced in your chat messages using the @ menu. This is useful when you want an agent to read, process, or act on a specific file.
+
+### How to reference a file
+
+1. Type **@** in the chat input field
+2. Start typing the file name or path
+3. Select the file from the results — it shows the file icon, name, and path
+4. The file path is inserted into your message, and the agent can access the file during its run
+
+<Tip>
+Use the filesystem browser to locate a file and copy its path, then paste it into the chat if you prefer not to use the @ search.
+</Tip>
+
+Files appear in the @ menu alongside agents, workforces, and saved prompts. For more on using agents and other @ mentions, see the [Chat introduction](/get-started/chat/introduction).