@@ -2,14 +2,18 @@
 
 [![Maven Central](https://img.shields.io/maven-central/v/io.dapr/dapr-sdk.svg?label=Maven%20Central&style=flat)](https://central.sonatype.com/artifact/io.dapr/dapr-sdk) [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/dapr/java-sdk/.github%2Fworkflows%2Fbuild.yml?branch=master&label=Build&logo=github)](https://github.com/dapr/java-sdk/actions/workflows/build.yml) [![codecov](https://codecov.io/gh/dapr/java-sdk/branch/master/graph/badge.svg)](https://codecov.io/gh/dapr/java-sdk) [![GitHub License](https://img.shields.io/github/license/dapr/java-sdk?style=flat&label=License&logo=github)](https://github.com/dapr/java-sdk/blob/master/LICENSE) [![FOSSA Status](https://app.fossa.com/api/projects/custom%2B162%2Fgithub.com%2Fdapr%2Fjava-sdk.svg?type=shield)](https://app.fossa.com/projects/custom%2B162%2Fgithub.com%2Fdapr%2Fjava-sdk?ref=badge_shield) [![GitHub issue custom search in repo](https://img.shields.io/github/issues-search/dapr/java-sdk?query=type%3Aissue%20is%3Aopen%20label%3A%22good%20first%20issue%22&label=Good%20first%20issues&style=flat&logo=github)](https://github.com/dapr/java-sdk/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) [![Discord](https://img.shields.io/discord/778680217417809931?label=Discord&style=flat&logo=discord)](http://bit.ly/dapr-discord) [![YouTube Channel Views](https://img.shields.io/youtube/channel/views/UCtpSQ9BLB_3EXdWAUQYwnRA?style=flat&label=YouTube%20views&logo=youtube)](https://youtube.com/@daprdev) [![X (formerly Twitter) Follow](https://img.shields.io/twitter/follow/daprdev?logo=x&style=flat)](https://twitter.com/daprdev)
 
-This is the Dapr SDK for Java, including the following features:
+The Java SDK for [Dapr](https://dapr.io): durable workflows, actors, pub/sub, state, service invocation, bindings and Spring Boot integration.
 
-* PubSub
-* Service Invocation
-* Binding
-* State Store
-* Actors
-* Workflows
+* **Docs:** [Java SDK documentation](https://docs.dapr.io/developing-applications/sdks/java/)
+* **API reference:** [Javadoc](https://dapr.github.io/java-sdk/)
+
+## Workflows
+
+Write durable workflows in plain Java with `dapr-sdk-workflows`. Workflow state is persisted by Dapr, so a workflow picks up where it left off after a crash or restart.
+
+* [Workflow overview](https://docs.dapr.io/developing-applications/building-blocks/workflow/workflow-overview/)
+* [Java SDK documentation](https://docs.dapr.io/developing-applications/sdks/java/)
+* [Workflow examples](./examples/src/main/java/io/dapr/examples/workflows/)
 
 ## Getting Started
 
@@ -33,30 +37,12 @@ flowchart LR
 For the full list of available APIs, see the [Dapr API reference](https://docs.dapr.io/reference/api/)
 
 ### Pre-Requisites
-* SDKMAN! installed (recommended):
-    * [SDKMAN!](https://sdkman.io)
-* Java IDE installed:
-    * [IntelliJ](https://www.jetbrains.com/idea/download/)
-    * [Eclipse](https://www.eclipse.org/downloads/)
-    * [Apache NetBeans](https://netbeans.apache.org/download/index.html)
-    * [Visual Studio Code](https://code.visualstudio.com/Download)
-    * Any other IDE for Java that you prefer.
-* Install one of the following build tools for Java:
-    * [Maven 3.x](https://maven.apache.org/install.html)
-    * [Gradle 6.x](https://gradle.org/install/)
-* If needed, install the corresponding plugin for the build tool in your IDE, for example:
-    * [Maven in IntelliJ](https://www.jetbrains.com/help/idea/maven.html)
-    * [Gradle in IntelliJ](https://www.jetbrains.com/help/idea/gradle-settings.html)
-    * [Maven in Eclipse with m2e](https://projects.eclipse.org/projects/technology.m2e)
-    * [Gradle in Eclipse with Buildship](https://projects.eclipse.org/projects/tools.buildship)
-* An existing Java Maven or Gradle project. You may also start a new project via one of the options below:
-    * [New Maven project in IntelliJ](https://www.jetbrains.com/help/idea/maven-support.html#create_new_maven_project)
-    * [Maven in 5 minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html)
-    * [Install toxiproxy-server binary](https://github.com/Shopify/toxiproxy/releases)
+* JDK 17 or later
+* [Maven 3.x](https://maven.apache.org/install.html) or [Gradle](https://gradle.org/install/)
+* An existing Java Maven or Gradle project. To start a new one, see [Maven in 5 minutes](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html).
+* The [Dapr CLI](https://docs.dapr.io/getting-started/install-dapr-cli/), to run your application with a Dapr sidecar locally
 
-### Install JDK
-
-If using [SDKMAN!](https://sdkman.io), execute `sdk env install` to install the required JDK.
+IDE setup and the tools needed to work on the SDK itself are under [Development](#development).
 
 ### Importing Dapr's Java SDK
 
@@ -69,7 +55,9 @@ Two BOMs are published:
 - **`io.dapr:dapr-sdk-bom`** — core SDK modules (`dapr-sdk`, `dapr-sdk-actors`, `dapr-sdk-workflows`, `dapr-sdk-autogen`, `durabletask-client`, `testcontainers-dapr`) plus security-patched transitive dependencies (Netty, Jackson, commons-compress, commons-codec).
 - **`io.dapr.spring:dapr-spring-bom`** — Spring-specific modules (`dapr-sdk-springboot`, `dapr-spring-*`). Imports `dapr-sdk-bom` transitively, so Spring users only need this single BOM.
 
-Pick the one that matches your project. Importing a BOM ensures you inherit security fixes for transitive dependencies like the Netty CVEs.
+`durabletask-client` is the gRPC client and worker for the Durable Task engine that runs Dapr workflows; `dapr-sdk-workflows` pulls it in, so you do not add it yourself.
+
+Pick the one that matches your project. Importing a BOM ensures you inherit security fixes for transitive dependencies like the Netty CVEs. With a BOM imported, the version is set once on the BOM and left off each Dapr dependency.
 
 ##### Core (non-Spring) projects
 
@@ -90,23 +78,20 @@ For Maven:
   </dependencyManagement>
 
   <dependencies>
-    <!-- Dapr's core SDK with all features, except Actors. -->
+    <!-- Dapr's core SDK with all features, except Actors and Workflows. -->
     <dependency>
       <groupId>io.dapr</groupId>
       <artifactId>dapr-sdk</artifactId>
-      <version>1.19.0</version>
     </dependency>
-    <!-- Dapr's SDK for Actors (optional). -->
+    <!-- Dapr's SDK for Workflows (optional). -->
     <dependency>
       <groupId>io.dapr</groupId>
-      <artifactId>dapr-sdk-actors</artifactId>
-      <version>1.19.0</version>
+      <artifactId>dapr-sdk-workflows</artifactId>
     </dependency>
-    <!-- Dapr's SDK integration with SpringBoot (optional). -->
+    <!-- Dapr's SDK for Actors (optional). -->
     <dependency>
       <groupId>io.dapr</groupId>
-      <artifactId>dapr-sdk-springboot</artifactId>
-      <version>1.19.0</version>
+      <artifactId>dapr-sdk-actors</artifactId>
     </dependency>
     ...
   </dependencies>
@@ -119,8 +104,10 @@ For Gradle:
 dependencies {
     implementation platform('io.dapr:dapr-sdk-bom:1.19.0')
 
-    // Dapr's core SDK with all features, except Actors.
-    compile('io.dapr:dapr-sdk:1.19.0')
+    // Dapr's core SDK with all features, except Actors and Workflows.
+    implementation 'io.dapr:dapr-sdk'
+    // Dapr's SDK for Workflows (optional).
+    implementation 'io.dapr:dapr-sdk-workflows'
     // Dapr's SDK for Actors (optional).
     implementation 'io.dapr:dapr-sdk-actors'
 }
@@ -204,9 +191,11 @@ For Maven:
 For Gradle:
 ```groovy
 dependencies {
-    implementation 'io.dapr:dapr-sdk:1.19.0'
-    implementation 'io.dapr:dapr-sdk-actors:1.19.0'
-    implementation 'io.dapr:dapr-sdk-springboot:1.19.0'
+    def daprVersion = '1.19.0'
+
+    implementation "io.dapr:dapr-sdk:${daprVersion}"
+    implementation "io.dapr:dapr-sdk-actors:${daprVersion}"
+    implementation "io.dapr:dapr-sdk-springboot:${daprVersion}"
 }
 ```
 
@@ -248,7 +237,7 @@ You can find a [step-by-step tutorial showing this integration here](./spring-bo
 
 ### API Documentation
 
-Please, refer to our [Javadoc](https://dapr.github.io/java-sdk/) website.
+See the [Javadoc](https://dapr.github.io/java-sdk/) for the API reference, and the [Java SDK documentation](https://docs.dapr.io/developing-applications/sdks/java/) for guides.
 
 ### Reactor API
 
@@ -325,6 +314,14 @@ Most exceptions thrown from the SDK are instances of `DaprException`. `DaprExcep
 
 ## Development
 
+### Tools
+
+* JDK 17. With [SDKMAN!](https://sdkman.io), run `sdk env install` in the repo root to install the JDK pinned in `.sdkmanrc`.
+* Maven is not needed: use the wrapper, `./mvnw`.
+* A Java IDE, for example [IntelliJ](https://www.jetbrains.com/idea/download/), [Eclipse](https://www.eclipse.org/downloads/), [Apache NetBeans](https://netbeans.apache.org/download/index.html) or [Visual Studio Code](https://code.visualstudio.com/Download), with Maven support if it needs a plugin:
+    * [Maven in IntelliJ](https://www.jetbrains.com/help/idea/maven.html)
+    * [Maven in Eclipse with m2e](https://projects.eclipse.org/projects/technology.m2e)
+
 ### Update URL to fetch proto files
 
 Change the `dapr.proto.baseurl` property below in [pom.xml](./pom.xml) to point to the URL for the desired commit hash in Git if you need to target a proto file that is not been merged into master yet. 
@@ -349,7 +346,7 @@ Note: You may need to run `./mvnw clean` after changing this setting to remove a
 ### Running Integration Tests (ITs)
 
 #### Pre-Requisites
-* [Pre-Requisites for the SDK](#pre-requisites)
+* The [development tools](#tools)
 * Docker installed and running
   * [Docker Desktop](https://www.docker.com/products/docker-desktop)
 * Bash shell
@@ -365,7 +362,7 @@ As a starting point for running the Integration Tests, first run `./mvnw clean i
 
 #### Backing services (managed automatically by Testcontainers)
 
-The integration tests use [Testcontainers](https://testcontainers.com/) to start and manage every backing service they depend on — Redis, Zipkin, MongoDB, Kafka, and the Dapr control plane (`placement` and `scheduler`) — automatically at test runtime.
+The integration tests use [Testcontainers](https://testcontainers.com/) to start and manage every backing service they depend on — Redis, Zipkin, MongoDB, Kafka, [Toxiproxy](https://github.com/Shopify/toxiproxy) for the resiliency tests, and the Dapr control plane (`placement` and `scheduler`) — automatically at test runtime.
 
 There is no separate step to bring these services up: you only need a running Docker daemon. Testcontainers pulls the required images and starts/stops the containers as the tests run.