add content versioning updates

content/guides/02.content/6.content-versioning.md

@@ -10,8 +10,9 @@ use content versioning, including drafting content without publishing it, and mo
 
 ## Concepts
 
-- **Version**: a version of an item is a snapshot that gets copied from the current version or main item, allowing you to safely make changes and later promote to be the main item.
-- **Main**: the main item is the default item that is displayed to users. It is the "source of truth" for all versions.
+- **Version**: A snapshot of an item that allows you to safely make changes without affecting the current version or main item. Versions can be promoted to become the new main item.
+- **Main**: The published version of your content that is live and visible to users. All new versions are created from the main item.
+- **Draft**: a reserved global version that is automatically available when content versioning is enabled. The draft version provides a dedicated workspace for making changes before publishing to main, and appears empty until edits are saved.
 - **Promote**: when a version is promoted, it becomes the main item that is displayed to users.
 - **Revision**: revisions are individual changes to items made within a version or main item. Directus keeps track of all changes made, so you're able to view the history of modifications and revert to a previous state.
 
@@ -26,16 +27,50 @@ The version field is a dynamic variable can be added to the live preview URL so
 
 Navigate to **Settings** > **Data Model**, select the collection that you want to enable content versioning for, and scroll down to the content versioning section. Toggle "Enable Versions" and save your data model.
 
+## Working with the Draft Version
+
+When content versioning is enabled for a collection, a global draft version is automatically available for all items. This reserved version provides a safe workspace for preparing changes before publishing to your live content.
+
+![Content versioning draft](/img/versioning-draft.png)
+
+### Understanding the Draft Version
+
+The draft version:
+- Appears automatically in the version list for all items with versioning enabled
+- Shows as empty until you make edits
+- Transforms from a virtual placeholder to an actual version when you save changes
+- Uses "**draft**" as a reserved version key that cannot be used for custom versions
+- Can be customized with a different display name, though it defaults to "Draft"
+
+::callout{icon="material-symbols:warning"}
+**Backward Compatibility**  
+The reserved global "draft" version was introduced in Directus 11.15.0. If you previously had custom versions with the key "draft", they will be preserved with their current names but cannot be deleted. The reserved draft version will coexist with your existing draft versions.
+::
+
+### Using Draft in the Visual Editor
+
+The Visual Editor integrates seamlessly with the draft version, allowing you to preview and edit changes in context:
+
+1. **Switch versions** using the dropdown in the Visual Editor header to toggle between "Main" and "Draft"
+2. **Edit items** that have content in the active version - items are only directly editable when they exist in the selected version
+3. **Preview changes** using the version-aware preview URL before publishing to main
+4. **Fallback behavior** - items without content in the selected version display their main version content (read-only)
+
+::callout{icon="material-symbols:info-outline"}
+**Version-Aware Editing**  
+When working in a specific version like draft, only items that have content saved in that version will show edit affordances. Other items fall back to displaying their main version content without automatically creating new version entries.
+::
+
+
 ## Creating a New Version
 
-![Creating a new version in the content module](/img/comparison_create-version.png)
+![Creating a new version in the content module](/img/versions-example.png)
 
 Open an item within your versioned collection. At the top of the item view, you will notice a dropdown with the main Content Version displayed as "main". Select "Create Version" and provide a key and a name for the new version. You can then save your new version.
 
 ::callout{icon="material-symbols:info-outline"}
 **Version Source**  
-All new versions originate from the main item. This implies that the main item acts as the single source of truth
-for other versions.
+All new versions originate from the main item. This implies that the main item acts as the single source of truth for other versions. The draft version is always available and doesn't need to be manually created.
 ::
 
 ## Making Changes to a Version
@@ -48,7 +83,7 @@ Upon saving the changes, you'll notice that the main item remains unaffected, wh
 
 ## Comparing and Promoting a Version
 
-![Promoting a version, comparing its changes](/img/comparison_promote-version.png)
+![Promoting a version, comparing its changes](/img/versions-example-comparison.png)
 
 
 Promoting a version makes it the main (current) version of your content.
@@ -65,14 +100,25 @@ Promoting a version makes it the main (current) version of your content.
 
 Once promoted, this version becomes the active content, and the previous main item is preserved in the version history. 
 
-After promoting a version, you can choose to keep or delete the version.
+After promoting a version, you can choose to keep or delete the version. For the global draft version, you'll see options to "Discard Edits" or "Keep Edits" instead of "Delete Version" or "Keep Version".
 
 ::callout{icon="material-symbols:info-outline"}
 **Programmatically Implement Content Versioning**  
 You have the option to integrate Content Versioning through the API. To learn how to accomplish this, please refer to
 our [API reference documentation](/api/versions).
 ::
 
+## Configuring Visual Editor for Versions
+
+To enable version-aware previewing in the Visual Editor:
+
+1. Navigate to **Settings** > **Data Model** and select your collection
+2. In the Visual Editor settings, configure your preview URL to include the `version` variable
+3. Example preview URL: `https://your-site.com/preview?item={{id}}&version={{version}}`
+
+The Visual Editor will automatically pass the active version to your preview, allowing you to see draft changes in the context of your actual site layout.
+
+
 ## Revisions and Content Versioning
 
 Under the hood, revisions are stored in the `directus_revisions` collection. In bigger projects this collection