feat: direct CRUD in both stacks

guides/uis/fiori.md

@@ -448,6 +448,61 @@ Content-Type: application/json
 
 For more details, see the [official UI5 documentation](https://ui5.sap.com/#/topic/ed9aa41c563a44b18701529c8327db4d).
 
+### Direct CRUD <Beta />
+
+By default, all modifications to draft-enabled entities go through the [draft choreography](#draft-choreography-how-draft-editing-works), optimized for human users working with SAP Fiori UIs.
+Technical consumers such as remote-services or AI-agents typically need to create and update data directly instead.
+Activating Direct CRUD with <Config>cds.fiori.direct_crud:true</Config> enables the best of both worlds, restoring standard CRUD operations on active entities while keeping the full draft feature set intact.
+
+To achieve this, SAP Fiori Elements' default draft creation is redirected to a collection-bound action via `@Common.DraftRoot.NewAction`.
+This frees `POST` requests to create active instances directly — the same behavior as without draft enablement.
+
+#### Create an active instance directly:
+
+```http
+POST /Books
+Content-Type: application/json
+
+{
+  "ID": 123
+}
+```
+
+#### Create a new draft instance by action:
+
+```http
+POST /Books/CatalogService.draftNew
+Content-Type: application/json
+
+{}
+```
+
+#### Update an active instance directly:
+
+```http
+PUT /Books(ID=123)
+Content-Type: application/json
+
+{
+  "title": "How to be more active"
+}
+```
+
+:::warning Draft locks still apply
+Directly updating an active entity does **not** bypass draft locks.
+If an existing draft locks the entity, any direct update is blocked to prevent losing draft changes upon activation.
+See draft lock configuration for [Node.js](../../node.js/fiori#draft-locks) or [Java](../../java/fiori-drafts#draft-lock).
+:::
+
+Direct CRUD is also a prerequisite for [SAP Fiori Elements Mass Edit](https://sapui5.hana.ondemand.com/sdk/#/topic/965ef5b2895641bc9b6cd44f1bd0eb4d.html), which lets users change multiple objects with the same editable properties in one step — without creating individual drafts per row.
+
+:::warning Additional entry point
+Both Direct CRUD and Mass Edit create additional entry points to your application.
+Custom handlers are triggered with delta payloads rather than the complete business object.
+:::
+
+[Learn more about Direct CRUD events in **Java**.](../../java/fiori-drafts#bypassing-draft-flow){.learn-more}
+
 ### Validating Drafts
 
 With Fiori draft state messages, you benefit from the following improvements without any change in your application code:
@@ -491,6 +546,7 @@ You can add your validation logic before the operation handler for either CRUD o
 
 <div id="query-data-draft-enabled" />
 
+
 ### Query Drafts Programmatically
 
 To access drafts in code, you can use the [`.drafts` reflection](../../node.js/cds-reflect#drafts).
@@ -500,6 +556,7 @@ SELECT.from(Books.drafts) //returns all drafts of the Books entity
 
 [Learn how to query drafts in Java.](../../java/fiori-drafts#draftservices){.learn-more}
 
+
 ## Use Roles to Toggle Visibility of UI elements
 
 In addition to adding [restrictions on services, entities, and actions/functions](../security/authorization#restrictions), there are use cases where you only want to hide certain parts of the UI for specific users. This is possible by using the respective UI annotations like `@UI.Hidden` or `@UI.CreateHidden` in conjunction with `$edmJson` pointing to a singleton.

java/fiori-drafts.md

@@ -136,7 +136,8 @@ GET /v4/myservice/myentity?$filter=IsActiveEntity eq true
 
 ## Bypassing the SAP Fiori Draft Flow { #bypassing-draft-flow }
 
-It's possible to create and update data directly without creating intermediate drafts. For example, this is useful when prefilling draft-enabled entities with data or in general, when technical components deal with the API exposed by draft-enabled entities. To achieve this, use the following requests. You can register event handlers for the corresponding events to validate incoming data:
+With [Direct CRUD](../guides/uis/fiori#direct-crud) enabled, you can create and update active entities directly without intermediate drafts, if they are not locked by another user.
+The following table shows the HTTP requests and corresponding CAP Java events:
 
 | HTTP / OData request                            | Event constant name                                      | Default implementation                               |
 | ----------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------- |
@@ -150,10 +151,6 @@ These events have the same semantics as described in section [Handling CRUD even
 With the 4.8.0 release, CAP Java introduced a mode where POST without `IsActiveEnitity=true` results in the `CqnService.EVENT_CREATE` (creation of an active entity) for the given entity. This mode is only active when the CDS property `cds.draft.post-active` is set to `true` and the entity is annotated with `@Common.DraftRoot.NewAction`. The annotation value needs to be the name of an unbound action in the same service of the entity. If the entity has a key with the type `UUID`, the action needs no further parameter. Otherwise, the action needs the key values of the entity as parameters.
 :::
 
-::: warning
-Directly updating the active entity does **not** bypass the [Draft Lock](#draft-lock). If an existing draft locks the active entity, the system blocks any attempt to update it. This ensures that the system does not lose changes to the active entity when you subsequently activate a draft.
-:::
-
 ## Draft Lock { #draft-lock }
 
 An entity with a draft is locked from being edited by other users until either the draft is saved or a timeout is hit (15 minutes by default). You can configure this timeout by the following application configuration property:

node.js/fiori.md

@@ -191,48 +191,12 @@ It can occur that inactive drafts are still in the database after the configured
 
 ## Bypassing Drafts {.deprecated}
 
-Use [Direct CRUD](#direct-crud) instead.
+Use [Direct CRUD](../guides/uis/fiori#direct-crud) instead.
 
 Until the next major release (`cds10`), you can still activate the draft bypass without also allowing direct CRUD via <Config>cds.fiori.bypass_draft:true</Config>.
 
 
 
-## Direct CRUD <Beta />
-
-With <Config>cds.fiori.direct_crud:true</Config>, creating or modifying active instances directly is possible without creating drafts.
-This comes in handy when technical services without a UI interact with each other.
-
-That is, you can then create and modify active instances directly:
-
-```http
-POST /Books
-
-{
-  "ID": 123
-}
-```
-
-```http
-PUT /Books(ID=123)
-
-{
-  "title": "How to be more active"
-}
-```
-
-For this, the default draft creation behavior by SAP Fiori Elements is redirected to a collection-bound action via annotation `@Common.DraftRoot.NewAction`.
-The thereby freed `POST` request to draft roots without specifying `IsActiveEntity` leads to the creation of an active instance (as it would without draft enablement).
-
-The feature is required to enable [SAP Fiori Elements Mass Edit](https://sapui5.hana.ondemand.com/sdk/#/topic/965ef5b2895641bc9b6cd44f1bd0eb4d.html), allowing users to change multiple objects with the
-same editable properties without creating drafts for each row.
-
-:::warning Additional entry point
-Note that this feature creates additional entry points to your application. Custom handlers are triggered with delta
-payloads rather than the complete business object.
-:::
-
-
-
 ## Programmatic APIs <Beta />
 
 You can programmatically invoke draft actions with the following APIs: