Release October 26 (#2961)

Author: smahati

.hyperspace/pull_request_bot_review_focus.md

@@ -1,7 +1,4 @@
----
-description: 'Does a detailed edit on the current file(s).'
-tools: ['read', 'agent', 'edit', 'todo', 'search']
----
+# capire documentation review focus
 
 ### ROLE
 You are a helpful editor for a technical writer. Your task is to review and improve the text while ensuring that it adheres to a structured set of writing rules. All categories are of equal priority—no rule should be prioritized over another.
@@ -72,7 +69,7 @@ Focus on content-level accessibility based on WCAG guidelines. Prioritize Level
 - Make sure that sentences are complete and that images, code blocks, and so on are not in between overflowing sentences.
 
 7. Consistency
-Use the `search` tool to check consistency across the repo. Report findings but do not auto-fix — flag locations for the author to review.
+Check consistency across the repo. Report findings but do not auto-fix — flag locations for the author to review. Identify questionable changes, and search the repository or cap.cloud.sap for related terms and references.
 
 - **Terminology**: Identify terms, product names, or UI labels introduced or changed in the diff. Search the repo for prior uses of the old term and flag files where the wording may be inconsistent or outdated.
 - **Renamed identifiers**: When a variable, class, method, config key, or file is renamed in the diff, search the repo for references to the old name and list any files that likely need updating.

.vitepress/config.js

@@ -141,8 +141,8 @@ const siteURL = new URL(process.env.SITE_HOSTNAME || 'http://localhost:4173/docs
 if (!siteURL.pathname.endsWith('/'))  siteURL.pathname += '/'
 config.themeConfig.capire = {
   versions: {
-    java_services: '5.1.1',
-    java_cds4j: '5.1.1',
+    java_services: '5.2.0',
+    java_cds4j: '5.2.0',
     cloud_sec_ams: '3.8.1'
   },
   gotoLinks: [],

.vitepress/lib/code-groups/restoreCodeGroupPreferences.js

@@ -89,13 +89,19 @@
   }
 
   const restoreHashScroll = () => {
-    if (hashScrollPending) {
-      history.replaceState(null, '', window.location.pathname + window.location.search + initialHash)
-      requestAnimationFrame(() => {
-        scrollToHash(initialHash)
-        hashScrollPending = false
-      })
-    }
+    if (!hashScrollPending) return
+
+    // Put the hash back into the URL as soon as we start handling it, so it
+    // survives even if the target element hasn't been rendered yet.
+    history.replaceState(null, '', window.location.pathname + window.location.search + initialHash)
+
+    // Don't finish until the target actually exists; the page content may still
+    // be hydrating. Until then, keep hashScrollPending so later retries can scroll.
+    const target = document.getElementById(decodeURIComponent(initialHash).slice(1))
+    if (!target) return
+
+    hashScrollPending = false
+    requestAnimationFrame(() => scrollToHash(initialHash))
   }
 
   const initialCodeGroupCount = applyToAllCodeGroups()
@@ -137,13 +143,34 @@
     }
   }
 
+  // Guarantee the hash is restored and scrolled to, even on pages that have no
+  // code groups (where the MutationObserver above never fires) and regardless of
+  // readyState when this inline head script runs. Retries each frame until the
+  // target has hydrated, then stops.
+  const pollRestore = () => {
+    const deadline = Date.now() + 3000
+    const tick = () => {
+      applyToAllCodeGroups()
+      restoreHashScroll()
+      if (hashScrollPending && Date.now() < deadline) {
+        requestAnimationFrame(tick)
+      } else {
+        stopObserving()
+      }
+    }
+    requestAnimationFrame(tick)
+  }
+
   if (document.readyState === 'loading') {
     document.addEventListener('DOMContentLoaded', () => {
       applyToAllCodeGroups()
       restoreHashScroll()
-      stopObserving()
+      if (hashScrollPending) pollRestore()
+      else stopObserving()
     })
-  } else if (!hashScrollPending) {
+  } else if (hashScrollPending) {
+    pollRestore()
+  } else {
     stopObserving()
   }
 })()

cds/cdl.md

@@ -2040,7 +2040,9 @@ service AdminService {
 ### Auto-Exposed Entities
 {#auto-expose}
 
-Annotate entities with `@cds.autoexpose` to automatically expose them in services containing entities with associations referring to them.
+Annotate entities with `@cds.autoexpose` to auto-expose them in services that contain entities with associations referring to them. Composition targets are auto-exposed without an annotation.
+
+#### Using @cds.autoexpose
 
 For example, given the following entity definitions:
 
@@ -2066,16 +2068,16 @@ service Zoo {
 }
 ```
 
-... would result in the service being automatically extended like this:
+... results in the service being automatically extended like this:
 
 ```cds
 extend service Zoo with { // auto-exposed entities:
-   @readonly entity Foo_bar as projection on Bar;
-   @readonly entity Foo_car as projection on Car;
+   entity Bar as projection on my.Bar;
+   entity Car as projection on my.Car;
 }
 ```
 
-You can still expose such entities explicitly, for example, to make them read-write:
+You can still expose such entities directly, for example, to make them read-write:
 
 ```cds
 service MyOrders {
@@ -2084,9 +2086,58 @@ service MyOrders {
 }
 ```
 
+#### Using Compositions
+
+Besides entities annotated with `@cds.autoexpose`, composition targets are auto-exposed.
+
+Example:
+```cds
+// schema.cds
+namespace travels;
+entity Travels {
+  key id : Integer;
+  bookings : Composition of many Bookings on Bookings.Travel = $self;
+}
+entity Bookings {
+  key Travel      : Association to Travels;
+  key Pos         : Integer;
+}
+```
+
+When `Travels` is exposed in a service ...
+
+```cds
+using { travels } from './schema.cds';
+service TravelService {
+  entity Travels as projection on travels.Travels
+}
+```
+
+... the composition target `Bookings` is auto-exposed as follows:
+
+```cds
+extend service TravelService with { // auto-exposed entity:
+   entity Bookings as projection on travels.Bookings;
+}
+```
+
 [Learn more about **CodeLists in `@sap/cds/common`**.](./common#code-lists){.learn-more}
 
 
+#### Switch Off Auto-Exposure
+
+To switch off auto-exposure of entities annotated with `@cds.autoexpose` in a service, annotate the service with `@cds.autoexpose: false`:
+```cds
+@cds.autoexpose: false
+service Zoo {
+  // ...
+  // Bar and Car are not auto-exposed in this service
+}
+```
+
+>[!important] Not valid for compositions
+> The `@cds.autoexpose: false` annotation does not affect auto-exposure of composition targets.
+
 
 ### Custom Actions and Functions {#actions}
 

get-started/bookshop.md

@@ -733,7 +733,8 @@ annotate AdminService.Books with {
 
 ### Custom Handlers in Node.js
 
-Prepare your project for custom coding in Node.js by adding the respective facet:
+Custom handlers are required for implementing business logic that cannot be expressed declarativatively, for example, through constraints. Prepare your project for custom coding in Node.js by adding the respective facet:
+
 ```shell
 cds add nodejs
 npm install
@@ -743,33 +744,22 @@ Put implementations for services into equally named _.js_ files placed next to a
 
 ```zsh
 ├─ srv/
-│ ├─ cat-service.cds # [!code focus]
-│ └─ cat-service.js # [!code focus]
+│ ├─ admin-service.cds # [!code focus]
+│ └─ admin-service.js # [!code focus]
 └─ ...
 ```
 
 ::: code-group
-```js [srv/cat-service.js]
-const cds = require('@sap/cds')
-class CatalogService extends cds.ApplicationService { init() {
-
-  // After READ handler on Books to add discount info
-  this.after ('READ', 'Books', results => results.forEach (book => {
-    if (book.stock > 111) book.title += ` -- 11% discount!`
-  }))
-
-  return super.init()
-}}
-module.exports = { CatalogService }
-```
-```js [srv/cat-service.mjs]
+```js [srv/admin-service.js]
 import cds from '@sap/cds'
-export class CatalogService extends cds.ApplicationService { init() {
+export class AdminService extends cds.ApplicationService { init() {
 
-  // After READ handler on Books to add discount info
-  this.after ('READ', 'Books', results => results.forEach (book => {
-    if (book.stock > 111) book.title += ` -- 11% discount!`
-  }))
+  /** Auto-fill integer primary keys, if necessary */
+  this.before ('CREATE', 'Books', async req => {
+    if (req.data.ID) return // skip if ID is already set
+    let {id} = await SELECT.one`max(ID) as id`.from(req.target)
+    req.data.ID = id + 4 // not safe, but ok for demo purposes
+  })
 
   return super.init()
 }}
@@ -852,11 +842,18 @@ While you **_can_** add custom handlers for standard CRUD events, you **_have to
 ```js [srv/cat-service.js]
   // Action handler for submitOrder
   this.on ('submitOrder', async req => {
-    let { book:id, quantity } = req.data
-    let affected = await UPDATE (Books,id)
+
+    // Try to reduce the stock of the ordered book, the good case
+    let { book:id, quantity=1 } = req.data
+    let { affected } = await UPDATE.entity (Books,id)
       .with `stock = stock - ${quantity}`
       .where `stock >= ${quantity}`
-    if (!affected) req.error `${quantity} exceeds stock for book #${id}`
+    if (affected) return //> done, the update was successful
+
+    // The update failed, let's check why, and respond accordingly...
+    let exists = await SELECT.one`stock`.from(Books,id)
+    if (!exists) req.error (404, `Book #${id} doesn't exist`)
+    else req.error (409, `${quantity} exceeds stock for book #${id}`, { id, quantity, ...exists })
   })
 ```
 :::

guides/ai/cap-agents.md

@@ -70,7 +70,7 @@ annotate CatalogService.submitOrder with @agent.hitl; // [!code focus]
 When the agent decides to call the action, the task pauses and transitions to the A2A [`input-required`](https://a2a-protocol.org/latest/specification/#413-taskstate) state instead of running the action immediately.
 
 > [!warning] Only supported by CAP Node.js
-> `@agent.hitl` is not yet supported by CAP Java
+> `@agent.hitl` is not yet supported by CAP Java.
 
 
 
@@ -248,7 +248,7 @@ DEBUG=agents cds watch
 > The plugin can automatically fetch required/missing credentials from local installations of supported LLMs, allowing you to work with zero additional configuration.
 
 > [!warning] CAP Node.js only
-> Auto configuration from local Claude and OpenCode installations is not supported by CAP Java
+> Auto configuration from local Claude and OpenCode installations is not supported by CAP Java.
 
 ### Using Chat Preview <Alpha/>
 
@@ -269,7 +269,7 @@ Also answer the questions that the agent asks you back.
 ![Chat conversation in Chat Preview](chat-preview-bookshop.png)
 
 > [!tip] Embedded with the CAP application
-> Essentially we see that the CAP-level agent accomplishes the same functionality than the generic agent that comes with _OpenCode_. The main difference is that it is tightly integrated with the CAP application, allowing for more seamless interaction with the underlying services and data models. Also the end user doesn't need any local AI client like _OpenCode_, nor do they need access to an LLM directly.
+> Essentially we see that the CAP-level agent accomplishes the same functionality as the generic agent that comes with _OpenCode_. The main difference is that it is tightly integrated with the CAP application, allowing for more seamless interaction with the underlying services and data models. Also the end user doesn't need any local AI client like _OpenCode_, nor do they need access to an LLM directly.
 
 
 ## Served out of the box
@@ -352,9 +352,9 @@ For details on configuring and using audit logging, refer to the documentation a
 
 ### Persistence
 
-The CAP-based harness provides short-term memory for agents by storing conversational and checkpoints in the connected primary database.
+The CAP-based agent harness provides short-term memory out-of-the-box via the connected primary database – that is in _SQLite_ in local dev, _SAP HANA_ in production.
 
-Agents can leverage this short-term memory to maintain context across multiple interactions within a session.
+This allows agents to persist conversational context and workflow checkpoints, so that they can resume sessions seamlessly even after server restarts, as well as boosting scalability in clustered environments. In addition, it provides a foundation for implementing long-term memory, monitoring and analytics on agent interactions.
 
 
 
@@ -406,9 +406,7 @@ The plugin can also export traces to [MLflow](https://mlflow.org/docs/latest/llm
 ```
 :::
 
-When enabled, an _MLflow_ exporter is added as a **second span processor** alongside any existing exporter (Dynatrace, Cloud Logging, Grafana, etc.),
-and the plugin automatically adds the following `mlflow.*` span attributes to existing OTel spans so the MLflow OTLP ingestion endpoint assembles them
-into proper MLflow traces — no additional SDK required.
+When enabled, an _MLflow_ exporter is added as a **second span processor** alongside any existing exporter (Dynatrace, Cloud Logging, Grafana, etc.), and the plugin automatically adds the following `mlflow.*` span attributes to existing OTel spans so the MLflow OTLP ingestion endpoint assembles them into proper MLflow traces — no additional SDK required.
 
 | Attribute                | Source                                                                                                |
 |--------------------------|-------------------------------------------------------------------------------------------------------|
@@ -552,17 +550,17 @@ cds:
 ```
 :::
 
-| Kind     | Description                                                                 |
-|----------|-----------------------------------------------------------------------------|
-| `aicore` | The default for `production` and `hybrid`, connects to SAP AI Core          |
-| `auto`   | The default for `development`, using local Claude or OpenCode configuration |
-| `mock`   | A pure mock for `development`, provides dummy responses when called         |
+| Kind     | Description                                                                        |
+|----------|------------------------------------------------------------------------------------|
+| `aicore` | The default for `production` and `hybrid`, connects to SAP AI Core                 |
+| `auto`   | The default for `development`, using local Claude, Codex or OpenCode configuration |
+| `mock`   | A pure mock for `development`, provides dummy responses when called                |
 
-See [SAP AI Core → Create a Service Instance](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-service-instance) for how to create an instance.vite
+See [SAP AI Core → Create a Service Instance](https://help.sap.com/docs/sap-ai-core/sap-ai-core-service-guide/create-service-instance) for how to create an instance.
 
 
 > [!tip] Automatically Fetching Credentials
-> In development profile, with the pre-configured `auto` kind, the plugin tries to fetch missing credentials from local installation of [Claude Code](https://claude.ai) or [OpenCode](https://opencode.ai).
+> In development profile, with the pre-configured `auto` kind, the plugin tries to fetch missing credentials from local installation of [Claude Code](https://claude.ai), [Codex](https://openai.com/codex/) or [OpenCode](https://opencode.ai).
 > This allows you to work with local LLM instances without providing any additional config at all.
 
 
@@ -581,5 +579,5 @@ See section [_Quotas_](#quotas) above for details.
 ## SAP API Policy
 
 > [!caution]
-> CAP-level agents as documented herein must not be used as gateways or proxies for SAP Application APIs. The _cap/agents_ plugins are not an SAP-endorsed architecture, data service, or service-specific pathway under section 2.2.2 of the [_SAP API Policy_](https://help.sap.com/docs/business-accelerator-hub/sap-business-accelerator-hub/sap-api-policy) and is not an endorsed mechanism for exposing, proxying, or providing agentic access to SAP Application APIs.
-> Any use of SAP Application APIs must be in accordance with the [_SAP API Policy_](https://help.sap.com/docs/business-accelerator-hub/sap-business-accelerator-hub/sap-api-policy). For SAP-endorsed patterns on agentic access to SAP Application APIs, consult the [_SAP Architecture Center_](https://architecture.learning.sap.com/docs/ref-arch/98efa0) reference architectures.
+> CAP-level agents as documented herein must not be used as gateways or proxies for SAP Application APIs. The `@cap-js/agents` plugin is not an SAP-endorsed architecture, data service, or service-specific pathway under section 2.2.2 of the [_SAP API Policy_](https://help.sap.com/docs/business-accelerator-hub/sap-business-accelerator-hub/sap-api-policy) and is not an endorsed mechanism for exposing, proxying, or providing agentic access to SAP Application APIs.
+> Any use of SAP Application APIs must be in accordance with the [_SAP API Policy_](https://help.sap.com/docs/business-accelerator-hub/sap-business-accelerator-hub/sap-api-policy). For SAP-endorsed patterns on agentic access to SAP Application APIs, consult the [_SAP Architecture Center_](https://architecture.learning.sap.com/docs/ref-arch/98efa0) reference architectures.

guides/ai/cap-mcp.md

@@ -125,9 +125,9 @@ Instead of annotating an existing service with `@mcp` and exposing all its entit
 
 ::: code-group
 ```cds [srv/mcp-service.cds]
-using { CatalogService } from './cat-service';
+using { AdminService } from './admin-service';
 
-@agent service BookshopService {
+@mcp service BooksService {
 
   @readonly entity Authors as projection on AdminService.Authors excluding {
     createdBy, modifiedBy,
@@ -139,9 +139,6 @@ using { CatalogService } from './cat-service';
     genre.name as genre,
     currency.name as currency,
   }
-
-  @agent.hitl
-  action submitOrder ( book: Books:ID, quantity: Integer );
 }
 ```
 :::
@@ -524,4 +521,4 @@ Future versions of the adapter may add support for data changes using CREATE, UP
 
 > [!caution]
 > The CAP MCP adapter must not be used as a gateway or proxy for SAP Application APIs. The adapter is not an SAP-endorsed architecture, data service, or service-specific pathway under section 2.2.2 of the [_SAP API Policy_](https://help.sap.com/docs/business-accelerator-hub/sap-business-accelerator-hub/sap-api-policy) and is not an endorsed mechanism for exposing, proxying, or providing agentic access to SAP Application APIs.
-> Any use of SAP Application APIs must be in accordance with the [_SAP API Policy_](https://help.sap.com/docs/business-accelerator-hub/sap-business-accelerator-hub/sap-api-policy). For SAP-endorsed patterns on agentic access to SAP Application APIs, consult the [_SAP Architecture Center_](https://architecture.learning.sap.com/docs/ref-arch/98efa0) reference architectures.
+> Any use of SAP Application APIs must be in accordance with the [_SAP API Policy_](https://help.sap.com/docs/business-accelerator-hub/sap-business-accelerator-hub/sap-api-policy). For SAP-endorsed patterns on agentic access to SAP Application APIs, consult the [_SAP Architecture Center_](https://architecture.learning.sap.com/docs/ref-arch/98efa0) reference architectures.

guides/deploy/microservices.md

@@ -354,7 +354,7 @@ build-parameters:
 Add [security configuration](../security/authentication) using the command:
 
 ```shell
-cds add xsuaa --for production
+cds add xsuaa
 ```
 
 Add the admin role

guides/deploy/to-kyma.md

@@ -194,7 +194,7 @@ cds build --production
 
 # Buildpack commands
 pack build bookshop-srv:latest --path gen/srv --builder builder-jammy-base --env BP_NODE_RUN_SCRIPTS=""
-pack build bookshop-html5-deployer:latest --path app/html5-deployer --builder builder-jammy-base --env BP_NODE_RUN_SCRIPTS=""
+pack build bookshop-html5-deployer:latest --path .deploy/html5-deployer --builder builder-jammy-base --env BP_NODE_RUN_SCRIPTS=""
 
 # Final assembly and deployment, e.g.
 helm upgrade --install bookshop ./gen/chart --namespace bookshop --wait --wait-for-jobs --timeout=10m