Update README files

CONTRIBUTING.md

@@ -31,6 +31,45 @@ The following rule governs code contributions:
 - Contributions must be licensed under the [Apache 2.0 License](./LICENSE)
 - Due to legal reasons, contributors will be asked to accept a Developer Certificate of Origin (DCO) when they create the first pull request to this project. This happens in an automated fashion during the submission process. SAP uses [the standard DCO text of the Linux Foundation](https://developercertificate.org/).
 
+## CI and Release
+
+### CI Checks
+
+Every pull request to `main` and every push to `main` runs the following checks (see [`.github/workflows/pipeline.yml`](.github/workflows/pipeline.yml)):
+
+| Job | What it enforces |
+|---|---|
+| `tests` | Unit tests (`mvn test -P '!with-integration-tests'`) on Java 17 and 21 |
+| `integration-tests` | Full integration tests on Java 17 and 21 |
+| `local-mtx-tests` | MTX lifecycle tests using a local sidecar (`mvn verify -pl integration-tests/mtx-local/srv`) on Java 17 and 21 |
+| `sonarqube-scan` | SonarQube static analysis |
+| `codeql` | CodeQL security scanning (`security-extended` queries) on Java/Kotlin and GitHub Actions |
+| `blackduck` (main only) | BlackDuck full open-source compliance scan |
+
+Static analysis runs at **compile time on every build** via Maven plugins configured in the root `pom.xml`:
+
+- **Spotless** — Google Java Format + SAP license headers (enforced at `process-sources`)
+- **SpotBugs** — `effort=Max` (at `process-test-classes`)
+- **PMD + CPD** — SAP Cloud SDK ruleset (at `process-test-classes`)
+- **Maven Enforcer** — no duplicate dependency versions, requires Maven 3.6.3+ and Java 17+
+
+Integration tests live in [`integration-tests/`](integration-tests/README.md) — see that README for test modules, run commands, and profiles.
+
+### JaCoCo Coverage
+
+Coverage is aggregated in the `coverage-report/` module using JaCoCo's `report-aggregate` goal. Each feature module runs `prepare-agent` to collect `.exec` data; the `coverage-report` module merges all `.exec` files and generates a single HTML report fed into SonarQube. Coverage thresholds (80% on new code) are enforced by SonarQube in the pipeline.
+
+To generate the report locally:
+
+```bash
+mvn clean verify
+# Report: coverage-report/target/site/jacoco-aggregate/index.html
+```
+
+### Release
+
+Releases are triggered by publishing a GitHub Release with a matching tag. The [`release.yml`](.github/workflows/release.yml) workflow gates on two protected environments (`release-approval` then `release`), verifies the POM `revision` matches the tag, runs BlackDuck, builds without integration tests, and deploys to Maven Central with GPG signing.
+
 ## Issues and Planning
 
 - We use GitHub issues to track bugs and enhancement requests.

README.md

@@ -4,7 +4,7 @@
 
 ## About this project
 
-This repository contains a collection of AI plugins for [CAP Java](https://cap.cloud.sap/docs/java/) applications, leveraging [SAP AI Core](https://help.sap.com/docs/sap-ai-core) and the SAP-RPT-1 foundation model.
+This repository contains a collection of AI plugins for [CAP Java](https://cap.cloud.sap/docs/java/) applications, leveraging [SAP AI Core](https://help.sap.com/docs/sap-ai-core), the SAP-RPT-1 foundation model, and SAP Document AI.
 
 ### Plugins
 
@@ -16,32 +16,17 @@ This repository contains a collection of AI plugins for [CAP Java](https://cap.c
 
 ### Starter
 
-For the simplest setup, add the **`cds-starter-ai`** dependency which bundles both plugins:
-
-```xml
-<dependency>
-    <groupId>com.sap.cds</groupId>
-    <artifactId>cds-starter-ai</artifactId>
-    <version>${cds-ai.version}</version>
-</dependency>
-```
-
-```json
-"dependencies": {
-    "@cap-js/ai": "^1"
-}
-```
-
-> Note: [`cds-feature-sap-document-ai`](cds-feature-sap-document-ai/README.md) is not part of `cds-starter-ai` yet - it will be added once the plugin supports multi-tenancy. Add it as an explicit dependency in your application if you need it today.
+See [`cds-starter-ai`](cds-starter-ai/README.md) for the quickest setup.
 
 ## Prerequisites
 
 - Java 17+
 - CAP Java 4.9+
 - Node.js 20+ with `@sap/cds-dk` 9+ (for CDS build tooling)
-- An [SAP AI Core](https://help.sap.com/docs/sap-ai-core) service binding (for production use)
+- An [SAP AI Core](https://help.sap.com/docs/sap-ai-core) service binding (for `cds-feature-ai-core` and `cds-feature-recommendations`)
+- A [SAP Document Information Extraction](https://help.sap.com/docs/document-ai) service binding (for `cds-feature-sap-document-ai`)
 
-Without an AI Core binding the plugins fall back to mock implementations for local development.
+Without the respective service binding, each plugin falls back to a mock or degraded mode for local development.
 
 ## Samples
 
@@ -54,7 +39,7 @@ mvn clean install     # build all modules
 mvn test              # run unit tests
 ```
 
-For per-plugin details (configuration, programmatic API, multi-tenancy behaviour) see the individual module READMEs. For integration tests against a real AI Core instance see [`integration-tests/spring`](integration-tests/spring).
+For per-plugin details (configuration, programmatic API, multi-tenancy behaviour) see the individual module READMEs. For integration tests against a real AI Core instance see [`integration-tests/`](integration-tests/README.md).
 
 ## Support, Feedback, Contributing
 

cds-feature-recommendations/README.md

@@ -2,7 +2,7 @@
 
 AI-powered field recommendations for SAP Fiori UIs in CAP Java applications, leveraging SAP AI Core and the SAP-RPT-1 foundation model.
 
-## How It Works
+## Features
 
 The plugin generically hooks into any draft-enabled entity that has properties with a value help. When a user edits a draft record, the plugin:
 
@@ -98,6 +98,11 @@ annotate Books with {
     }]
   }
 }
+
+// Opt out a specific field
+annotate Books with {
+  genre @UI.RecommendationState: 0;
+}
 ```
 
 #### Adding the SAP_Recommendations navigation property manually

cds-feature-sap-document-ai/README.md

@@ -9,6 +9,7 @@ A CAP Java plugin that integrates [SAP Document AI](https://help.sap.com/docs/do
 - [Integration Guide](#integration-guide)
 - [Usage](#usage)
   - [CDS Model](#cds-model)
+- [Multi-Tenancy](#multi-tenancy)
 - [Bookshop Sample](#bookshop-sample)
   - [Running without a Document AI service binding](#running-without-a-die-service-binding)
   - [Running with a Document AI service binding (hybrid mode)](#running-with-a-die-service-binding-hybrid-mode)
@@ -190,7 +191,9 @@ Submit a document via your application. The plugin logs progress at `INFO` level
 
 > **Note:** In the current version, document extraction can only be triggered programmatically via event emission, as shown in the [Integration Guide](#integration-guide). Annotation-based triggering (e.g. declaratively marking an entity field or action to trigger extraction) is not yet supported and is planned for a future release.
 
-> **Note:** Multitenancy is not implemented in the current version and is planned for a future release. Until then, the plugin should only be used in single-tenant deployments.
+## Multi-Tenancy
+
+Multi-tenancy is not implemented in the current version and is planned for a future release. The `tenantId` field is stored on the `ExtractionJob` entity as groundwork.
 
 ### CDS Model
 
@@ -382,6 +385,13 @@ The plugin communicates with the SAP Document Information Extraction service via
 
 ---
 
+## Known Limitations
+
+- **Multi-tenancy** — not implemented; all jobs run in a single-tenant context. Planned for a future release.
+- **Annotation-based triggering** — document extraction can only be initiated programmatically via event emission; declarative triggering is not yet supported.
+
+---
+
 ## Monitoring and Logging
 
 All plugin log statements are prefixed with `[sap-document-ai]` to facilitate log filtering. The plugin uses SLF4J and is configured through the standard logging framework of the host application.

cds-starter-ai/README.md

@@ -0,0 +1,49 @@
+# cds-starter-ai
+
+A zero-source convenience module that bundles all SAP AI plugins for CAP Java into a single dependency.
+
+## What it includes
+
+| Module | Scope | Description |
+|---|---|---|
+| [`cds-feature-ai-core`](../cds-feature-ai-core/README.md) | `compile` | Bridges CAP Java to SAP AI Core — resource groups, deployments, configurations, inference client |
+| [`cds-feature-recommendations`](../cds-feature-recommendations/README.md) | `runtime` | AI-powered field recommendations for Fiori Elements draft UIs |
+
+`cds-feature-sap-document-ai` is currently **not** included as the plugin is not yet fully multi-tenant-ready. It will be added to the starter once MT support is complete. Add it as an explicit dependency if you need it today.
+
+## Setup
+
+```xml
+<dependency>
+    <groupId>com.sap.cds</groupId>
+    <artifactId>cds-starter-ai</artifactId>
+    <version>${cds-ai.version}</version>
+</dependency>
+```
+
+Both plugins auto-register via Java's `ServiceLoader` — no further code changes are required.
+
+For the Node.js side of `cds-feature-recommendations`, also add the `@cap-js/ai` CDS plugin to your `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@cap-js/ai": "^1"
+  }
+}
+```
+
+## Prerequisites
+
+- Java 17+
+- CAP Java 4.9+
+- An [SAP AI Core](https://help.sap.com/docs/sap-ai-core) service binding (for production use)
+- A [SAP Document Information Extraction](https://help.sap.com/docs/document-ai) service binding (once `cds-feature-sap-document-ai` is included)
+
+Without the respective bindings the plugins fall back to mock implementations — useful for local development.
+
+## Related
+
+- [SAP AI Core Documentation](https://help.sap.com/docs/sap-ai-core)
+- [SAP AI SDK for Java](https://github.com/SAP/ai-sdk-java)
+- [`cds-feature-sap-document-ai`](../cds-feature-sap-document-ai/README.md) — standalone document extraction plugin

integration-tests/README.md

@@ -45,7 +45,7 @@ Aggregated code coverage is produced by the `coverage-report/` module at the pro
 
 1. Each module that runs tests has the JaCoCo agent attached (`prepare-agent`), which writes a `target/jacoco.exec` file during test execution.
 2. The `coverage-report` module (built last in the reactor) merges all `.exec` files into a single `target/jacoco-merged.exec`.
-3. It then generates an aggregated HTML/XML report via `jacoco:report-aggregate` and runs `jacoco:check` against configurable thresholds.
+3. It then generates an aggregated HTML/XML report via `jacoco:report-aggregate`. Coverage thresholds are enforced by SonarQube in the pipeline, not by JaCoCo check goals.
 
 ### Generating the report
 
@@ -61,18 +61,14 @@ coverage-report/target/site/jacoco-aggregate/index.html
 
 ### Thresholds
 
-Per-module thresholds are defined in `coverage-report/pom.xml`:
-
-| Module | Instruction | Branch | Complexity |
-|--------|-------------|--------|------------|
-| `cds-feature-ai-core` | 0% | 0% | 0% |
-| `cds-feature-recommendations` | 80% | 80% | 80% |
+Coverage thresholds are enforced by SonarQube in the CI pipeline (80% on new code).
 
 ### Coverage data sources
 
 The merged report combines execution data from:
 
 - `cds-feature-ai-core/target/jacoco.exec` (unit tests)
 - `cds-feature-recommendations/target/jacoco.exec` (unit tests)
+- `cds-feature-sap-document-ai/target/jacoco.exec` (unit tests)
 - `integration-tests/spring/target/jacoco.exec` (integration tests)
 - `integration-tests/mtx-local/srv/target/jacoco.exec` (MTX integration tests, only when profile is active)