docs: clarify draft parameter and _status field interaction (#14723)

### What?

Clarifies how the `draft` parameter and `_status` field work together in
the drafts documentation.

### Why?

The existing docs implied that the `draft` parameter controls whether
documents are published or not, but that's not accurate. The `draft`
parameter controls validation and write location, while `_status`
controls the actual publish state. This led to confusion about why
`draft: false` doesn't publish documents and when each parameter takes
precedence.

### How?

- Separated the explanation of `draft` parameter (validation + write
location) from `_status` field (publish state)
- Clarified that on initial create, both `draft: true/false` write to
main collection
- Added reference table showing all combinations of `draft` and
`_status` for create/update operations
- Updated examples to show explicit `_status` usage

Fixes #13393

Author: PatrikKozak

docs/versions/drafts.mdx

@@ -49,11 +49,9 @@ Within the Admin UI, if drafts are enabled, a document can be shown with one of
   specify if you are interacting with drafts or with live documents.
 </Banner>
 
-#### Updating or creating drafts
+#### Using the `draft` parameter
 
-If you enable drafts on a collection or global, the `create` and `update` operations for REST, GraphQL, and Local APIs expose a new option called `draft` which allows you to specify if you are creating or updating a **draft**, or if you're just sending your changes straight to the published document.
-
-For example:
+When drafts are enabled, the `create`, `update`, `find`, and `findByID` operations for REST, GraphQL, and Local APIs expose a `draft` parameter. For write operations, it controls validation and where data is written. For read operations, it determines whether to return draft versions.
 
 ```ts
 // REST API
@@ -65,7 +63,7 @@ await payload.create({
   data: {
     // your data here
   },
-  draft: true, // This is required to create a draft
+  draft: true,
 })
 
 // GraphQL
@@ -76,29 +74,80 @@ mutation {
 }
 ```
 
-**Required fields**
+**Understanding `draft` parameter and `_status` field**
+
+The `draft` parameter and `_status` field work together but serve different purposes:
+
+**`draft` parameter** - Controls two things:
+
+1. **Validation**: When `draft: true`, required fields are not enforced, allowing you to save incomplete documents
+2. **Write location**: Determines whether the main collection document is updated
+   - `draft: true` - Saves ONLY to versions table (main collection unchanged)
+   - `draft: false` or omitted - Saves to BOTH main collection AND versions table
+
+**`_status` field** - Indicates whether a document is published or in draft state
+
+- Defaults to `'draft'` when not explicitly provided
+- Can be explicitly set in your data to `'published'` or `'draft'`
+
+**First document creation**
+
+When you first create a document, it's always written to the main collection (since no document exists yet):
+
+- If you don't specify `_status`, it defaults to `_status: 'draft'`
+- A version is also created in the versions table
+- The `draft` parameter controls validation but doesn't change where the initial document is written
+
+**Subsequent updates**
 
-If `draft` is enabled while creating or updating a document, all fields are considered as not required, so that you can save drafts that are incomplete.
+After initial creation, the `draft` parameter controls where your updates are written:
 
-Setting `_status: "draft"` will not bypass the required fields. You need to set `draft: true` as shown in the previous examples.
+- **`draft: true`** - Only the versions table is updated; the main collection document remains unchanged
+- **`draft: false` or omitted** - Both the main collection and versions table are updated
+
+**Important:** The `draft` parameter does NOT control whether a document is published or not. A document remains with `_status: 'draft'` by default unless you explicitly set `_status: 'published'` in your data.
+
+**Publishing a document**
+
+To publish a document, you must explicitly set `_status: 'published'` in your data. When you do this:
+
+- If you use `draft: false` or omit it, the main collection will be updated with the published status
+- If you use `draft: true`, the `_status: 'published'` takes precedence and will still update the main collection as published (overriding the `draft: true` behavior)
+
+**Quick reference**
+
+| Operation | `draft` param      | `_status` in data    | Result                                                         |
+| --------- | ------------------ | -------------------- | -------------------------------------------------------------- |
+| Create    | `true` or `false`  | omitted              | Main collection updated with `_status: 'draft'`                |
+| Create    | `true` or `false`  | `'published'`        | Main collection updated with `_status: 'published'`            |
+| Update    | `true`             | omitted or `'draft'` | Only versions table updated, main collection unchanged         |
+| Update    | `true`             | `'published'`        | Main collection updated with `_status: 'published'` (override) |
+| Update    | `false` or omitted | omitted              | Main collection updated with `_status: 'draft'`                |
+| Update    | `false` or omitted | `'published'`        | Main collection updated with `_status: 'published'`            |
+
+**Required fields**
+
+Setting `_status: "draft"` will not bypass required field validation. You need to set `draft: true` to save incomplete documents as shown in the previous examples.
 
 #### Reading drafts vs. published documents
 
 In addition to the `draft` argument within `create` and `update` operations, a `draft` argument is also exposed for `find` and `findByID` operations.
 
-If `draft` is set to `true` while reading a document, **Payload will automatically replace returned document(s) with their newest drafts** if any newer drafts are available.
+When `draft` is set to `true` while reading a document, **Payload will return the most recent version from the versions table**, regardless of whether it's a draft or published document.
+
+**Example scenario:**
 
-**For example, let's take the following scenario:**
+1. You create a document with `_status: 'published'` (published in main collection)
+1. You update with `draft: true` to make changes without affecting the published version
+1. You update again with `draft: true` to make more draft changes
 
-1. You create a new collection document and publish it right away
-1. You then make some updates, and save the updates as a draft
-1. You then make some further updates, and save more updates as another draft
+At this point, your published document remains unchanged in the main collection, and you have two newer draft versions in the `_[collectionSlug]_versions` table.
 
-Here, you will have a published document that resides in your main collection, and then you'll have two _newer_ drafts that reside in the `_[collectionSlug]_versions` database collection.
+When you fetch the document with a standard `find` or `findByID` operation, the published document from the main collection is returned and draft versions are ignored.
 
-If you simply fetch your created document using a `find` or `findByID` operation, your published document will be returned and the drafts will be ignored.
+However, if you pass `draft: true` to the read operation, Payload will return the most recent version from the versions table. In the scenario above with two draft versions, you'll get the latest (second) draft.
 
-But, if you specify `draft` as `true`, Payload will automatically replace your published document's content with content coming from the most recently saved `version`. In this case, as we have created _two_ versions in the above scenario, Payload will send back data from the newest (second) draft and your document will appear as the most recently drafted version instead of the published version.
+**Note:** If there are no newer drafts (e.g., you published a document and haven't made draft changes since), querying with `draft: true` will still return the latest version from the versions table, which would be the same published content as in the main collection.
 
 <Banner type="error">
   **Important:** the `draft` argument on its own will not restrict documents