mintlify · ethanpalm · May 26, 2026 · May 26, 2026 · May 26, 2026 · May 26, 2026
diff --git a/docs.json b/docs.json
@@ -89,13 +89,16 @@
                     "root": "editor/index",
                     "pages": [
                       "editor/tutorial",
+                      "editor/collaborate",
                       "editor/branching-and-publishing",
                       "editor/live-preview",
+                      "editor/share-a-preview",
                       "editor/pages",
                       "editor/navigation",
                       "editor/keyboard-shortcuts",
                       "editor/configurations",
-                      "editor/settings"
+                      "editor/settings",
+                      "editor/git-essentials"
                     ]
                   },
                   "create/text",

diff --git a/editor/branching-and-publishing.mdx b/editor/branching-and-publishing.mdx
@@ -79,34 +79,7 @@
 
 ## Preview your changes
 
-Every time you save changes to a feature branch, Mintlify builds a preview deployment—a temporary URL where your changes render exactly as they look when published.
-
-### Access and share a preview
-
-1. Click **Publish** in the editor toolbar.
-1. In the publish menu, click the preview URL. The URL format is `organization-branch-name.mintlify.app`.
-    <Frame>
-      <img src="/images/editor/preview-url-light.png" alt="Preview URL emphasized in the publish menu." className="block dark:hidden" />
-      <img src="/images/editor/preview-url-dark.png" alt="Preview URL emphasized in the publish menu." className="hidden dark:block" />
-    </Frame>
-
-Copy the URL and send it to reviewers. The preview updates automatically each time you save to the branch.
-
-### Restrict access to previews
-
-Preview URLs are publicly accessible by default. To restrict access to members of your Mintlify organization, enable preview authentication in the [Add-ons](https://app.mintlify.com/products/addons) page of your dashboard.
-
-### Share editor links
-
-To invite a teammate to a specific page on a branch, copy the URL from your browser's address bar and share it. Anyone with access to your Mintlify organization can open the link directly in their editor session.
-
-The URL format is:
-
-```text
-https://app.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath}
-```
-
-For example: `https://app.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx`
+Every time you save changes to a feature branch, Mintlify builds a preview deployment—a temporary URL where your changes render how they look when published. See [Share a preview](/editor/share-a-preview) for how to access, share, and restrict access to preview deployments.
 
 ## Review and merge pull requests
 
@@ -124,7 +97,7 @@

 ### Approve pull requests from the editor

 For GitHub repositories, reviewers can approve open pull requests in the editor. When a pull request is open, an **Approve pull request** button appears in the review panel if your account has permission to review it. Click **Approve pull request** when the changes are ready to be merged. The review status updates to **Approved** and the **Merge and publish** action becomes available.

 The approve action is not available for draft pull requests, pull requests you have already approved, or GitLab merge requests. Click **Open in GitLab** to approve a merge request in GitLab.

@@ -146,19 +119,9 @@
 
 ## Resolve conflicts
 
-Conflicts occur when your branch and the deployment branch have incompatible changes to the same files. For example, when you and a teammate edited the same lines in a file or moved a file to different locations.
-
-The editor displays a warning when conflicts block publishing. Follow the prompts to choose which version of each conflicting section to keep.
-
-## Collaborate in real time
-
-When multiple people open the same page on the same branch, they edit together in real time. Each person's cursor and edits are visible to everyone, with avatars shown in the toolbar.
-
-- Changes from all collaborators merge automatically. Two people editing the same section won't create conflicts.
-- Undo only affects your own edits.
-- If you lose your connection, edits save locally and sync when you reconnect.
+Conflicts occur when your branch and the deployment branch have incompatible changes to the same files. For example, if you and a teammate both edited the same lines, or a file was moved in two different directions.
 
-When the [Mintlify agent](/agent) edits a page through the API or MCP, it appears in the editor like any other collaborator. You see the agent's avatar in the toolbar and a live cursor at its most recent edit location. The cursor clears automatically after the agent finishes.
+When conflicts block publishing, the editor shows an error and prevents the publish from completing. Resolve conflicts by switching to your Git provider (GitHub or GitLab) and merging or rebasing the conflicting branches there, then return to the editor to publish.
 
 ## Git sync
 

diff --git a/editor/collaborate.mdx b/editor/collaborate.mdx
@@ -1,8 +1,8 @@
 ---
 title: "Collaborate in the web editor"
 sidebarTitle: "Collaborate"
-description: "Edit documentation with your team using real-time collaboration, live cursors, shareable editor links, branches, and pull request review workflows."
-keywords: ["editor", "collaboration", "real-time", "live editing", "branches", "pull requests", "preview deployments", "share links"]
+description: "Edit documentation with your team using real-time collaboration, live cursors, an AI agent chat panel, shareable editor links, branches, and pull request review workflows."
+keywords: ["editor", "collaboration", "real-time", "live editing", "branches", "pull requests", "preview deployments", "share links", "agent", "assistant"]
 ---
 
 Collaborate with your team on documentation using real-time editing and branch-based workflows.
@@ -11,25 +11,45 @@
 
 Multiple people can edit the same page at the same time. Changes from each person appear for everyone on the page.
 
-To collaborate on a page in real time, share the editor link for that page with your teammates. See [Share editor links](#share-editor-links) below.
-
-<Frame>
-  <img src="/images/editor/editor-light.png" className="block dark:hidden" alt="Web editor showing real-time collaboration with multiple cursors" />
-  <img src="/images/editor/editor-dark.png" className="hidden dark:block" alt="Web editor showing real-time collaboration with multiple cursors" />
-</Frame>
-
-### How real-time editing works
+To collaborate on a page in real time, share the editor link for that page with your teammates. See [Share a preview](/editor/share-a-preview#share-editor-links) for the URL format.
 
 When multiple team members edit the same branch, changes sync in real-time. Page content, navigation structure, and site configuration updates appear automatically for all collaborators without refreshing.
 
 - Each person's cursor and edits are visible to everyone on the page, with user avatars and names shown in the toolbar.
 - Changes merge automatically. Two people editing the same section won't cause conflicts.
 - Undo only affects your own changes—undoing won't revert another person's edits.
 - If you lose your network connection, your edits save locally and sync when you reconnect.
 
+## Chat with the agent in the editor
+
+The agent panel lets you chat with the [Mintlify agent](/agent) directly inside the editor. Open it by clicking the agent icon in the left sidebar. The panel sits to the left of the file explorer so you can chat and navigate files at the same time.
+
+### Start a session
+
+Type a prompt in the chat input and press Enter. The agent reads your docs and makes edits on the current branch.
+
+### Attach context
+
+Click the paperclip icon in the chat input to attach context to your message. You can attach:
+
+- **Files** — any file from your repository
+- **Pages** — specific documentation pages the agent should read or edit
+- **Divisions** — a tab, anchor, or other navigation section
+- **Inline text** — paste text directly into the attachment field
+
+Attaching context focuses the agent on the right part of your docs without requiring you to describe it in your prompt.
+
+### Review per-session diffs
+
+After the agent makes changes, a diff summary appears in the chat panel showing the changes. Click any file in the diff summary to navigate to that page in the editor.
+
+### Leave feedback
+
+Use the thumbs up and thumbs down buttons in the chat panel to rate the agent's response. This helps improve future results.
+
 ## See the agent's edits in real time
 
-When the [Mintlify agent](/agent) edits a page through the API or MCP, it appears in the web editor like any other collaborator. If you have the page open on the same branch, you see the agent's avatar and name at the top of the editor and a live cursor at the location of its most recent edit.
+When the [Mintlify agent](/agent) edits a page through the API, MCP, or the agent panel, it appears in the web editor like any other collaborator. If you have the page open on the same branch, you see the agent's avatar and name at the top of the editor and a live cursor at the location of its most recent edit.
 
 Use this to:
 
@@ -37,8 +57,12 @@
 - See which paragraph or block the agent just updated without diffing the file.
 - Coordinate with teammates and the agent on the same branch without overwriting each other's work.
 
 The agent's cursor clears automatically a short time after the agent finishes editing.
 
+## Send content to the assistant
+
+To send highlighted content to the [assistant](/assistant), select text in the editor. A floating toolbar appears above the selection. Click **Add to Assistant**. The selected content attaches to a new assistant conversation so you can ask questions or request changes without switching context.
+
 ## Branch-based collaboration
 
 Use branches to work on documentation updates in parallel without affecting your live site. If you aren't familiar with Git, see [Git essentials for the web editor](/editor/git-essentials).
@@ -68,33 +92,6 @@
   </Step>
 </Steps>
 
-## Preview deployments
-
-Preview deployments create temporary URLs where you can see your rendered changes before they go live. Use preview deployments to gather feedback on your changes.
-
-Every time you publish changes to a branch, the preview deployment updates automatically.
-
-### Access preview deployments
-
-1. Click **Publish** in the editor toolbar.
-2. Click the preview URL to open the preview deployment in a new tab. The URL format is `organization-branch-name.mintlify.app`.
-
-### Share previews
-
-Share the preview deployment URL with team members to gather feedback. Previews update automatically when you publish additional changes.
-
-### Preview authentication
-
-Preview URLs are publicly accessible by default. Enable preview authentication in the [Add-ons](https://app.mintlify.com/products/addons) page of your dashboard to restrict access to authenticated organization members.
-
-## Share editor links
-
-Share a direct link to a specific page in the editor with your teammates. Use editor links to collaborate on updates in real time or point teammates to a specific page.
-
-The editor URL updates automatically as you navigate between pages. Copy the URL from your browser's address bar to share it with teammates who have access to the editor.
-
-The URL format is: `https://app.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath}`
-
-For example, `https://app.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx` opens `quickstart.mdx` on the `main` branch.
+## Share previews and editor links
 
-Anyone with access to your Mintlify organization can use the link to open the file directly in the editor.
+See [Share a preview](/editor/share-a-preview) for how to share preview deployment URLs and editor links with your team.
diff --git a/editor/live-preview.mdx b/editor/live-preview.mdx
@@ -4,11 +4,11 @@ description: "Preview your documentation site in real time as you edit, with con
 keywords: ["editor", "preview", "live preview"]
 ---
 
-Preview your site while you edit. Live previews render pages exactly as they look when published, and update as you make changes to content, navigation, and configuration.
+Live preview renders your documentation site in a separate tab and updates as you make changes.
 
 ## Open live preview
 
-Click the <Icon icon="play" /> live preview button in the toolbar to open a live preview in a new tab.
+Click the <Icon icon="play" /> live preview button in the editor toolbar to open live preview in a new tab.
 
 <Frame>
   <img
@@ -23,17 +23,17 @@ Click the <Icon icon="play" /> live preview button in the toolbar to open a live
   />
 </Frame>
 
+Live preview reflects the current branch. Changes to content, navigation structure, and `docs.json` configuration all render immediately. Keep both tabs open to edit and preview side by side.
+
 <Note>
-  Live preview is only available for public documentation.
+  Live preview is only available for public documentation. If your site requires authentication, use a [preview deployment](/editor/share-a-preview) instead.
 </Note>
 
 ## Live preview versus preview deployments
 
 |  | Live preview | Preview deployment |
 |---|---|---|
-| **Speed** | Instant | Requires a build |
-| **Access** | Local URL | Shareable URL |
-| **Use when** | Reviewing changes while editing | Sharing with your team for review |
+| **Updates** | Instant, as you type | Requires a save to the branch |
+| **URL** | Local to your browser session | Shareable with anyone |
+| **Use when** | Checking your own changes while editing | Sharing with teammates or reviewing on another device |
 | **Availability** | While the editor is open | As long as the branch exists |
-
-Use live preview for immediate feedback while editing. When you need to share changes with your team or test on a different device, use a [preview deployment](/editor/branching-and-publishing#preview-your-changes).
diff --git a/editor/pages.mdx b/editor/pages.mdx
@@ -6,18 +6,42 @@
 
 ## Navigate files
 
-Browse pages in the **Navigation** tab of the left panel. Click a page to open it. Click the search icon or press <kbd>Cmd</kbd> + <kbd>K</kbd> (macOS) or <kbd>Ctrl</kbd> + <kbd>K</kbd> (Windows) to search by filename or page content.
+The left panel has two views: **Navigation** and **Files**.
+
+**Navigation** shows your documentation sidebar structure. Click a page to open it.
+
+**Files** shows the full file tree of your repository, including files that aren't in your navigation. Click any file to open it. Click the search icon or press <kbd>Cmd</kbd> + <kbd>K</kbd> (macOS) or <kbd>Ctrl</kbd> + <kbd>K</kbd> (Windows) to search by filename or page content.
+
+The browser tab title updates automatically to show the name of the file you have open, making it easier to tell pages apart when you have multiple tabs open.
 
 <Note>
   The web editor treats API specification files (OpenAPI and AsyncAPI) as read-only. To update a spec file, edit it in your preferred code editor and push the changes to your documentation repository.
 </Note>
 
+## Manage files and folders
+
+Use the file tree to organize your content:
+
+- **Create a folder**: Click the <Icon icon="folder-plus" /> new folder button at the top of the file tree, or right-click an existing folder and select **New folder**.
+- **Rename a file or folder**: Right-click the item and select **Rename**.
+- **Open unlisted files**: Click any Markdown or media file in the tree to open it, even if it isn't included in your navigation.
+
+Files you open from the tree that aren't in your navigation are unlisted — they exist in your repository but won't appear in your published documentation sidebar.
+
 ## Create new pages
 
+### Add a page to navigation
+
 1. Click the <Icon icon="plus" /> plus button in the navigation element where you want to add a page.
 1. Click **Add a page**.
 1. Enter a filename. The editor adds the `.mdx` extension automatically.
 
+### Create an unlisted page
+
+Unlisted pages exist in your repository but don't appear in navigation. They're useful for draft content, reusable snippets, or pages you plan to add to navigation later.
+
+To create an unlisted page, right-click any folder in the file tree and select **New file**. Enter a filename and the editor creates the page without adding it to navigation. You can add it to navigation later from the **Navigation** tab.
+
 ## Edit content
 
 Switch between visual and Markdown mode with the toggle in the toolbar.
@@ -33,7 +57,7 @@
 - **Link to another page**: Right-click a page in the navigation tree, click **Copy link**, then paste the link into your content. The editor recognizes internal links to other pages and converts them.
 - **Insert media from your project**: Drag an image or video from the navigation tree into the page to embed it inline. Supported formats include PNG, JPG, JPEG, GIF, WebP, SVG, MP4, and WebM.
 - **Insert an emoji**: Type <kbd>:</kbd> followed by a keyword to open the emoji picker.
 - **Edit a table**: When your cursor is inside a table, use the floating toolbar to add or remove rows and columns, or merge cells.

 **Markdown mode** gives you direct access to the MDX source. Use it for precise control over component properties and frontmatter.

@@ -58,7 +82,7 @@

 ### Table of contents

 In visual mode, the editor shows a minimap on the right side of the page that reflects the heading structure of your document. Hover over the minimap to expand it into a full table of contents. Click any heading to scroll to that section.

 ### Code block options

@@ -73,7 +97,7 @@

 Open the publish menu and click any changed file to enter diff view. The editor highlights differences between your draft and the last published version. If you're in visual mode, you see a visual diff. If you're in Markdown mode, you see a Markdown diff.

 Diff view is read-only. Click the <Icon icon="x" /> button next to the mode toggle to return to editing.

 ## Manage pages

@@ -90,7 +114,7 @@

 Hover over a page and click the gear icon, or right-click and select **Settings**, to configure:

 - **Title**, **Slug**, and **Sidebar title**: Control how the page appears in navigation and its URL.
 - **Description** and **Keywords**: Improve search and SEO.
 - **Layout**: Choose from standard, wide, centered, or custom.

@@ -102,7 +126,7 @@

 Type <kbd>/image</kbd> to upload a new image or select an existing one from your repository. Type <kbd>/video</kbd> to upload or select a video.

 You can also drag and drop files from your computer directly onto a page. In visual mode, the file inserts inline. In Markdown mode, the editor inserts the file path at your cursor position. Images save to your `images/` folder and videos to `videos/`.

 To reuse media that already lives in your project, drag an image or video file from the navigation tree onto the page. The editor embeds the asset inline.


diff --git a/editor/settings.mdx b/editor/settings.mdx
@@ -9,7 +9,7 @@
 - **Your settings** apply only to you and control how the editor's AI assists with your edits.
 - **Publishing settings** apply to everyone on a deployment and shape what happens when you commit changes and turn them into pull requests.
 
-You can configure both from the **Settings** menu in the editor.
+You can configure both from the settings panel. To open it, click the <Icon icon="settings" /> settings icon in the editor toolbar. The panel consolidates all per-editor preferences in one place.
 
 ## AI instructions
 
@@ -35,10 +35,9 @@
 
 ### Configure AI instructions
 
-1. Open the editor and click your avatar in the toolbar.
-2. Select **Settings**.
-3. In the **AI instructions** field, enter the guidance you want the AI to follow.
-4. Save your changes.
+1. Open the editor and click the <Icon icon="settings" /> settings icon in the toolbar.
+2. In the **AI instructions** field, enter the guidance you want the AI to follow.
+3. Save your changes.
 
 Example:
 
@@ -112,7 +111,7 @@

 - **Merge**: Creates a merge commit that preserves the full branch history.
 - **Squash**: Combines all commits in the branch into a single commit on your deployment branch.
 - **Rebase**: Replays each commit from the branch onto your deployment branch without a merge commit.

 The editor uses the selected method by default. If you pass an explicit merge method through the API or your Git provider's UI, that choice takes precedence.


diff --git a/editor/share-a-preview.mdx b/editor/share-a-preview.mdx
@@ -6,30 +6,34 @@
 
 ## Preview deployments
 
-Every time you save changes to a feature branch, Mintlify builds a preview deployment—a temporary URL that renders your changes exactly as they look when published. Use it to review your work or collect feedback before merging.
+Every time you save changes to a feature branch, Mintlify builds a preview deployment — a temporary URL that renders your changes exactly as they look when published. Use it to review your work or collect feedback before merging.
 
 ### Access your preview
 
 1. Click **Publish** in the editor toolbar.
 1. In the publish menu, click the preview URL. The URL format is `organization-branch-name.mintlify.app`.
 
+<Frame>
+  <img src="/images/editor/preview-url-light.png" alt="Preview URL in the publish menu." className="block dark:hidden" />
+  <img src="/images/editor/preview-url-dark.png" alt="Preview URL in the publish menu." className="hidden dark:block" />
+</Frame>
+
 ### Share your preview
 
-Copy the preview URL and send it to reviewers. The preview updates automatically each time you save to the branch.
+Copy the preview URL and send it to reviewers. The preview updates automatically each time you save to the branch, so reviewers always see your latest changes at the same URL.
 
 ### Restrict access to previews
 
 Preview URLs are publicly accessible by default. To restrict access to members of your Mintlify organization, enable preview authentication in the [Add-ons](https://app.mintlify.com/products/addons) page of your dashboard.
 
 ## Share editor links
 
-To invite a teammate to view or edit a specific page on a branch, copy the URL from your browser's address bar and share it. Anyone with access to your Mintlify organization can open the link directly in their editor session.
+To invite a teammate to view or edit a specific page on a branch, copy the URL from your browser's address bar and share it. Anyone with access to your Mintlify organization can open the link directly in their editor session on the same branch.
 
 The URL format is:
 
-```
+```text
 https://app.mintlify.com/{org}/{project}/editor/{branch}/~/{filepath}
 ```
 
 For example: `https://app.mintlify.com/acme/docs/editor/main/~/guides/quickstart.mdx`
-