diff --git a/get-started/feature-matrix.md b/get-started/feature-matrix.md
index bbdc1e216..66abfaf3e 100644
--- a/get-started/feature-matrix.md
+++ b/get-started/feature-matrix.md
@@ -55,7 +55,7 @@ Following is an index of the features currently covered by CAP, with status and
 | Bind application to remote services                                                 | `cds bind`                 |
 | Debug your application                                                              | `cds debug`                |
 | Login to multitenant SaaS application                                               | `cds login <app-url>`      |
-| Upgrade SaaS tenant(s) to latest versions                                           | `cds upgrade`              |
+| Upgrade SaaS tenant(s) to latest versions                                           | `cds upgrade-tenant`       |
 | Logout from multitenant SaaS application                                            | `cds logout`               |
 | Subscribe a tenant to a SaaS application                                            | `cds subscribe <tenant>`   |
 | Unsubscribe a tenant from a SaaS application                                        | `cds unsubscribe <tenant>` |
diff --git a/tools/cds-cli.md b/tools/cds-cli.md
index 7191a514e..c71e8f1bd 100644
--- a/tools/cds-cli.md
+++ b/tools/cds-cli.md
@@ -771,112 +771,31 @@ For example:
 - In VS Code, use the _Debug: Attach to Node Process_ command.
 - In Chrome browser, just open [chrome://inspect](chrome://inspect) and click _Inspect_.
 
-<!-- ## cds upgrade
+## cds upgrade <Beta/>
 
-`cds upgrade` scans your project for breaking changes in a new CDS major version and reports exactly where you are affected.
-
-The command evaluates migration rules against your project sources, configuration, and dependencies. It reports:
-
-- Which breaking changes affect your project
-- Where exactly in your code (file and line number)
-- What needs to change and how
-
-A typical scan takes seconds and covers about 40 rules for CDS 10.
-
-### Run the Command
+Use `cds upgrade` to assist you in upgrading your project to new/latest CDS versions.
+Run it like that in your project's root directory with a globally installed `@sap/cds-dk` version 10:
 
 ```sh
 cds upgrade
 ```
 
-Without a global installation:
-
+::: details Run without a global installation ...
 ```sh
 npx -p @sap/cds-dk@10 cds upgrade
 ```
+:::
 
+That will:
 
-The following table explains the options:
-
-| Flag       | Effect                                                                        |
-|------------|-------------------------------------------------------------------------------|
-| `--fix`    | Apply dependency version rewrites (and OpenRewrite recipes for Java projects) |
-| `--report` | Write `report.md` to `.cds-upgrade/`                                          |
-
-
-
-Before running the analysis, the command validates prerequisites: Node.js version, clean working tree, recognized project structure, and installed dependencies. Any issues appear as `[FAIL]` items in the output before the analysis begins.
-
-### Output
-
-#### Console
-
-By default, the command prints a compact summary to the terminal:
-
-```
-Environment Analysis
-
-  Node.js CAP project
-  cds-dk version: v10.0.1 → CDS 10
-  cds version: @sap/cds 9.9.1 (CDS 9)
-
-Code Analysis
-
-  10 rules with potential issues:
-
-    1  Fixed Bulk Inserts via REST
-    1  Fixed `cds.ql.clone()`
-    1  Fixed `srv.entities()` – texts entity access
-    1  Fixed Affinity for Decimals
-    2  Bypass Draft Choreography
-    1  hdbcds compiler backend removed
-    2  Decimals & Int64 as Strings
-    1  Fixed Service Results – legacy_srv_results flag
-    4  cds.requires.scheduling defaults to true — Scheduling Service auto-connects when a database is configured
-    2  Fixed `srv.entities()` – getter methods removed
-    16  matches total
-
-
-Run cds upgrade --fix to update dependency versions.
-Re-run with --report to write .cds-upgrade/report.md listing remaining code changes.
-```
-
-The output lists the match count and rule title for each affected rule.
-
-#### Report Files {#report}
-
-With `--report`, a human-readable report is written to `.cds-upgrade/report.md`. It groups findings by migration topic (matching the structure of the [migration guide](/releases/migration/cds10)). Each finding includes:
-
-- Migration context explaining what changed and how to address it
-- Match locations in `file:line` format
-- A link to the corresponding section on cap.cloud.sap
-
-Rules that cannot be checked automatically appear in a separate **Manual Review** section with guidance on what to look for.
-
-#### Understanding the Report
-
-Open `.cds-upgrade/report.md` and work through it section by section. Each finding includes:
-
-1. **What changed** - the breaking change explained, with examples
-2. **Where** - file and line in your code
-3. **What to do** - fix guidance from the migration guide
-
-Items that the CDS compiler can detect also surface as build errors after you upgrade. The report gives you a head start before the actual version bump.
-
-You can also pass the report to an AI coding agent to interpret findings in context, filter false positives, search for additional occurrences, and apply fixes directly.
-
-### After the Scan
-
-1. Fix the reported issues, guided by the report.
-2. Run `cds build` to confirm that compiler-level issues are resolved.
-3. Run your test suite to verify runtime behavior.
-
-### Limitations
+- Run preflight checks: Node.js version, clean working tree, installed dependencies.
+- Upgrade your project dependencies to the latest cds10 versions.
+- Scan your project for whether you're affected by breaking changes.
 
-- Detection is structural (pattern-based) — semantic-only issues require manual review or AI assistance.
-- Monorepo support is limited to one project root per invocation.
+See also:
 
-### Related
+- [Migration Guide for cds10](/releases/migration/cds10) — complete list of breaking changes
+- [Java Migration Guide](/java/migration) — migration steps for CAP Java projects
 
-- [Migration Guide for CDS 10](/releases/migration/cds10) — complete list of breaking changes
-- [Java Migration Guide](/java/migration) — migration steps for CAP Java projects -->
+> [!warning] Limitations
+> Scans for breaking changes is pattern-based, likely includes false positives; require detailed investigation and manual review.  Some breaking changes are not detectable automatically, for example, semantic-only issues or changes in behavior that do not affect the code structure.