From ace7a410168e25860f7c0ffc9d5d641bbfca7469 Mon Sep 17 00:00:00 2001
From: Mariya Yordanova <mariya.yordanova@sap.com>
Date: Thu, 29 Oct 2026 14:45:21 +0100
Subject: [PATCH 1/2] docs(cds-connect): add UPSI binding section and
 cross-link from cds-env

---
 node.js/cds-connect.md | 154 +++++++++++++++++++++++++++++++++++++++++
 node.js/cds-env.md     |   2 +-
 2 files changed, 155 insertions(+), 1 deletion(-)

diff --git a/node.js/cds-connect.md b/node.js/cds-connect.md
index d0f3fb0c69..a327b89f70 100644
--- a/node.js/cds-connect.md
+++ b/node.js/cds-connect.md
@@ -503,6 +503,160 @@ cds env get requires.<servicename>
 ```
 :::
 
+#### User-Provided Service Instances { #vcap-upsi }
+
+[User-Provided Service Instances (UPSIs)](https://docs.cloudfoundry.org/devguide/services/user-provided.html) always appear in `VCAP_SERVICES` under the `"user-provided"` key, regardless of what service they hold credentials for. A common use case is cross-account service instance sharing.
+
+Because all UPSIs share the same key, matching by kind label or type does not apply — only name and tag matching works. Use an explicit `vcap` config to override auto-matching:
+
+<style scoped>
+  .no-stripes tr:nth-child(2n) {
+    background-color:unset;
+  }
+</style>
+
+<table class="no-stripes">
+<thead>
+<tr>
+<th>CAP config</th>
+<th>VCAP_SERVICES</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+
+```json
+{
+  "cds": {
+    "requires": {
+      "my-service": {}
+    }
+  }
+}
+```
+</td>
+<td>
+
+```json
+{
+  "user-provided": [{
+    "name": "my-service",
+    "tags": []
+  }]
+}
+```
+</td>
+</tr>
+<tr>
+<td>
+
+```json
+{
+  "cds": {
+    "requires": {
+      "my-service": {}
+    }
+  }
+}
+```
+</td>
+<td>
+
+```json
+{
+  "user-provided": [{
+    "name": "my-upsi",
+    "tags": ["cds:my-service"]
+  }]
+}
+```
+</td>
+</tr>
+<tr>
+<td>
+
+```json
+{
+  "cds": {
+    "requires": {
+      "my-service": {
+        "kind": "my-kind"
+      }
+    }
+  }
+}
+```
+</td>
+<td>
+
+```json
+{
+  "user-provided": [{
+    "name": "my-upsi",
+    "tags": ["my-kind"]
+  }]
+}
+```
+</td>
+</tr>
+<tr>
+<td>
+
+```json
+{
+  "cds": {
+    "requires": {
+      "my-service": {
+        "vcap": { "name": "my-upsi" }
+      }
+    }
+  }
+}
+```
+</td>
+<td>
+
+```json
+{
+  "user-provided": [{
+    "name": "my-upsi",
+    "tags": []
+  }]
+}
+```
+</td>
+</tr>
+<tr>
+<td>
+
+```json
+{
+  "cds": {
+    "requires": {
+      "my-service": {
+        "vcap": { "tag": "my-tag" }
+      }
+    }
+  }
+}
+```
+</td>
+<td>
+
+```json
+{
+  "user-provided": [
+    { "name": "other-upsi", "tags": ["other-tag"] },
+    { "name": "my-upsi",   "tags": ["my-tag"] }
+  ]
+}
+```
+</td>
+</tr>
+</tbody>
+</table>
+
 ### In Kubernetes / Kyma { #in-kubernetes-kyma}
 
 CAP supports [servicebinding.io](https://servicebinding.io/) service bindings and SAP BTP service bindings created by the [SAP BTP Service Operator](https://github.com/SAP/sap-btp-service-operator).
diff --git a/node.js/cds-env.md b/node.js/cds-env.md
index c5d97a7477..9ae31f2d8d 100644
--- a/node.js/cds-env.md
+++ b/node.js/cds-env.md
@@ -325,7 +325,7 @@ add them to the `cds.requires` section.
 
 ### In `cds.requires.<service>` Settings
 
-Here, you can configure the services. Find details about the individual options in the documentation of [`cds.connect`](cds-connect#cds-env-requires).
+Here, you can configure the services. Find details about the individual options in the documentation of [`cds.connect`](cds-connect#cds-env-requires), including the [`vcap` property](cds-connect#vcap-services) for influencing how credentials are looked up in `VCAP_SERVICES`.
 
 ### Prototype-Chained Along `.kind` References
 

From 4d2cc7c76dc780eb60a482545e6f7b152a7547a8 Mon Sep 17 00:00:00 2001
From: mariayord <mariya.yordanova@sap.com>
Date: Fri, 30 Oct 2026 15:54:24 +0100
Subject: [PATCH 2/2] Update node.js/cds-env.md

Co-authored-by: sjvans <30337871+sjvans@users.noreply.github.com>
---
 node.js/cds-env.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/node.js/cds-env.md b/node.js/cds-env.md
index 9ae31f2d8d..d78e24f62a 100644
--- a/node.js/cds-env.md
+++ b/node.js/cds-env.md
@@ -325,7 +325,7 @@ add them to the `cds.requires` section.
 
 ### In `cds.requires.<service>` Settings
 
-Here, you can configure the services. Find details about the individual options in the documentation of [`cds.connect`](cds-connect#cds-env-requires), including the [`vcap` property](cds-connect#vcap-services) for influencing how credentials are looked up in `VCAP_SERVICES`.
+Here, you can configure the services. Find details about the individual options in the documentation of [`cds.connect`](cds-connect), specifically [Configuring Required Services](cds-connect#configuring-required-services) for how the service behaves and [Service Bindings](cds-connect#service-bindings) for how credentials are resolved.
 
 ### Prototype-Chained Along `.kind` References