diff --git a/code_snippets/java/src/main/java/develop/workflows/WorkflowSubmitter.java b/code_snippets/java/src/main/java/develop/workflows/WorkflowSubmitter.java
index 60b30e82..2c4412f9 100644
--- a/code_snippets/java/src/main/java/develop/workflows/WorkflowSubmitter.java
+++ b/code_snippets/java/src/main/java/develop/workflows/WorkflowSubmitter.java
@@ -2,6 +2,7 @@
 
 import dev.restate.sdk.client.Client;
 import dev.restate.sdk.client.SendResponse;
+import dev.restate.sdk.common.Output;
 
 public class WorkflowSubmitter {
 
@@ -20,10 +21,20 @@ public void submitWorkflow(Email email) {
         // <end_query>
 
         // <start_interact>
+        // Option 1: attach and wait for result
         boolean result = SignupWorkflowClient
                 .fromClient(restate, "someone")
                 .workflowHandle()
                 .attach();
+
+        // Option 2: peek to check if ready
+        Output<Boolean> peekOutput = SignupWorkflowClient
+                .fromClient(restate, "someone")
+                .workflowHandle()
+                .getOutput();
+        if(peekOutput.isReady()){
+            boolean result2 = peekOutput.getValue();
+        }
         // <end_interact>
 
     }
diff --git a/code_snippets/java/src/main/java/operate/invocations/Ingress.java b/code_snippets/java/src/main/java/operate/invocations/Ingress.java
index bb9c182b..ce7b1b15 100644
--- a/code_snippets/java/src/main/java/operate/invocations/Ingress.java
+++ b/code_snippets/java/src/main/java/operate/invocations/Ingress.java
@@ -34,9 +34,6 @@ public void myOneWayCallHandler(Context ctx) {
         GreetCounterObjectClient.fromClient(rs, "Mary")
                 .send()
                 .greet("Hi");
-
-        MyWorkflowClient.fromClient(rs, "wf-id-1")
-                .submit("input");
         // <end_one_way_call_java>
     }
 
@@ -70,77 +67,25 @@ public void attach() {
         Client rs = Client.connect("http://localhost:8080");
         SendResponse handle = GreeterServiceClient.fromClient(rs)
                 .send()
+                // mark
                 .greet("Hi", CallRequestOptions.DEFAULT.withIdempotency("abcde"));
 
         // ... do something else ...
 
-        // Attach later to retrieve the result
-        // withClass(1:3) highlight-line
+        // Option 1: Attach later to retrieve the result
+        // mark(1:3)
         String greeting = rs
                 .invocationHandle(handle.getInvocationId(), JsonSerdes.STRING)
                 .attach();
-        // <end_service_attach>
-    }
-
-    public void peekAtOutput(){
-        // <start_service_peek>
-        Client rs = Client.connect("http://localhost:8080");
-        SendResponse handle = GreeterServiceClient.fromClient(rs)
-                .send()
-                .greet("Hi", CallRequestOptions.DEFAULT.withIdempotency("abcde"));
-
-        // ... do something else ...
-
-        // Peek to see if the result is ready
-        // withClass(1:3) highlight-line
-        Output<String> output = rs
-            .invocationHandle(handle.getInvocationId(), JsonSerdes.STRING)
-            .getOutput();
-
-        if (output.isReady()) {
-            String result = output.getValue();
-        }
-        // <end_service_peek>
-    }
-
-    public void latchOntoWorkflow(){
-
-        // <start_workflow_attach>
-        Client rs = Client.connect("http://localhost:8080");
-        SendResponse handle = MyWorkflowClient
-                .fromClient(rs, "wf-id-1")
-                .submit("input");
-
-        // If you have access to the workflow handle:
-        // withClass(1:3) highlight-line
-        String response = rs
-                .invocationHandle(handle.getInvocationId(), JsonSerdes.STRING)
-                .attach();
 
-        // If you do not have access to the workflow handle, use the workflow ID:
-        String response2 = MyWorkflowClient.fromClient(rs, "wf-id-1")
-                // withClass(1:2) highlight-line
-                .workflowHandle()
-                .attach();
-        // <end_workflow_attach>
-
-        // <start_workflow_peek>
-        // If you have access to the workflow handle:
-        // withClass(1:3) highlight-line
+        // Option 2: Peek to see if the result is ready
+        // mark(1:3) 
         Output<String> output = rs
                 .invocationHandle(handle.getInvocationId(), JsonSerdes.STRING)
                 .getOutput();
-
         if (output.isReady()) {
             String result = output.getValue();
         }
-
-        // If you do not have access to the workflow handle, use the workflow ID:
-        Output<String> output2 = MyWorkflowClient.fromClient(rs, "wf-id-1")
-                // withClass(1:2) highlight-line
-                .workflowHandle()
-                .getOutput();
-        // <end_workflow_peek>
-
+        // <end_service_attach>
     }
 }
diff --git a/code_snippets/ts/src/develop/workflows/service.ts b/code_snippets/ts/src/develop/workflows/service.ts
index 56c6f161..dab99fdd 100644
--- a/code_snippets/ts/src/develop/workflows/service.ts
+++ b/code_snippets/ts/src/develop/workflows/service.ts
@@ -7,7 +7,7 @@ export default restate.object({
     handlers: {
         // <start_here>
         signUpUser: async (ctx: ObjectContext, email: string) => {
-            // focus(1:2)
+            // focus(1:3)
             const result = await ctx
                 .workflowClient<SignUpWorkflow>({name: "signup"}, "someone")
                 .run({email});
diff --git a/code_snippets/ts/src/develop/workflows/submit.ts b/code_snippets/ts/src/develop/workflows/submit.ts
index 957e430e..9484108d 100644
--- a/code_snippets/ts/src/develop/workflows/submit.ts
+++ b/code_snippets/ts/src/develop/workflows/submit.ts
@@ -7,7 +7,8 @@ async function signUpUser(user: User){
     // <start_submit>
     // import * as restate from "@restatedev/restate-sdk-clients";
     const rs = restate.connect({url: "http://localhost:8080"});
-    await rs.workflowClient<SignUpWorkflow>({name: "signup"}, "someone")
+    const handle = await rs
+        .workflowClient<SignUpWorkflow>({name: "signup"}, "someone")
         .workflowSubmit({email: user.email});
     // <end_submit>
 
@@ -18,9 +19,21 @@ async function signUpUser(user: User){
     // <end_query>
 
     // <start_attach>
-    const result = await rs
+    // Option 1: attach and wait for result with handle
+    const result1 = await rs.result(handle);
+
+    // Option 2: attach and wait for result with workflow ID
+    const result2 = await rs
         .workflowClient<SignUpWorkflow>({name: "signup"}, "someone")
         .workflowAttach();
+
+    // Option 3: peek to check if ready with workflow ID
+    const peekOutput = await rs
+        .workflowClient<SignUpWorkflow>({name: "signup"}, "someone")
+        .workflowOutput();
+    if(peekOutput.ready){
+        const result3 = peekOutput.result;
+    }
     // <end_attach>
 
 }
diff --git a/code_snippets/ts/src/operate/invocations/ingress.ts b/code_snippets/ts/src/operate/invocations/ingress.ts
index c1dc0e3c..ec5c4117 100644
--- a/code_snippets/ts/src/operate/invocations/ingress.ts
+++ b/code_snippets/ts/src/operate/invocations/ingress.ts
@@ -1,59 +1,48 @@
 import {greetCounterObject, greeterService} from "./utils";
 import {SendOpts} from "@restatedev/restate-sdk-clients";
 import {myWorkflow} from "../../concepts/invocations/utils";
-
-// <start_clients_import>
 import * as clients from "@restatedev/restate-sdk-clients";
-// <end_clients_import>
 
 const myPlainTSFunction = async () => {
     // <start_rpc_call_node>
+        // import * as clients from "@restatedev/restate-sdk-clients";
         const rs = clients.connect({url: "http://localhost:8080"});
         const greet = await rs.serviceClient(greeterService)
             .greet({greeting: "Hi"});
 
         const count = await rs.objectClient(greetCounterObject, "Mary")
             .greet({greeting: "Hi"});
-
-        // You cannot **submit** workflows via request-response with the clients.
-        // You can call the other handlers of workflows via request-response.
-        const response = await rs.workflowClient(myWorkflow, "wf-id-1")
-            .myOtherHandler({input: "Hi"});
     // <end_rpc_call_node>
 }
 
 const myPlainTSFunction2 = async () => {
     // <start_one_way_call_node>
+    // import * as clients from "@restatedev/restate-sdk-clients";
     const rs = clients.connect({url: "http://localhost:8080"});
     await rs.serviceSendClient(greeterService)
         .greet({greeting: "Hi"});
 
     await rs.objectSendClient(greetCounterObject, "Mary")
         .greet({greeting: "Hi"});
-
-    await rs.workflowClient(myWorkflow, "wf-id-1")
-        .workflowSubmit({input: "Hi"});
-    // You cannot yet do one-way calls to other handlers of the workflows
     // <end_one_way_call_node>
 }
 
 const myPlainTSFunction3 = async () => {
     // <start_delayed_call_node>
+    // import * as clients from "@restatedev/restate-sdk-clients";
     const rs = clients.connect({url: "http://localhost:8080"});
     await rs.serviceSendClient(greeterService)
         .greet({greeting: "Hi"}, SendOpts.from({ delay: 1000 }));
 
     await rs.objectSendClient(greetCounterObject, "Mary")
         .greet({greeting: "Hi"}, SendOpts.from({ delay: 1000 }));
-
-    // You cannot call any workflow handlers via delayed calls with the clients.
     // <end_delayed_call_node>
 }
 
 const servicesIdempotent = async () => {
     const request = {greeting: "Hi"}
-    // <start_service_idempotent>
     const rs = clients.connect({url: "http://localhost:8080"});
+    // <start_service_idempotent>
     await rs.serviceSendClient(greeterService)
         // withClass highlight-line
         .greet(request, SendOpts.from({ idempotencyKey: "abcde" }));
@@ -63,49 +52,17 @@ const servicesIdempotent = async () => {
 const servicesAttach = async () => {
     const request = {greeting: "Hi"}
     // <start_service_attach>
+    // import * as clients from "@restatedev/restate-sdk-clients";
     const rs = clients.connect({url: "http://localhost:8080"});
     // Send a message
     const handle = await rs.serviceSendClient(greeterService)
+        // mark
         .greet(request, SendOpts.from({ idempotencyKey: "abcde" }));
 
     // ... do something else ...
 
     // Attach later to retrieve the result
-    // withClass highlight-line
+    // mark
     const response = await rs.result(handle);
     // <end_service_attach>
 }
-
-const workflowAttach = async () => {
-    // <start_workflow_attach>
-    const rs = clients.connect({url: "http://localhost:8080"});
-
-    // Submit the workflow
-    const handle = await rs.workflowClient(myWorkflow, "wf-id-1")
-        .workflowSubmit({input: "Hi"});
-
-    // ... do something else ...
-
-    // Attach by using the handle:
-    // withClass highlight-line
-    const result = await rs.result(handle);
-
-    // Or, attach by using the workflow ID (from another service):
-    // withClass highlight-line
-    const result2 = await rs.workflowClient(myWorkflow, "wf-id-1").workflowAttach();
-    // <end_workflow_attach>
-}
-
-const workflowPeek = async () => {
-    // <start_workflow_peek>
-    const rs = clients.connect({url: "http://localhost:8080"});
-
-    // Peek at the output by using the workflow ID (from another service):
-    // withClass highlight-line
-    const output = await rs.workflowClient(myWorkflow, "wf-id-1").workflowOutput();
-    // If the workflow is ready, do something with the result
-    if (output.ready) {
-        console.log(output.result);
-    }
-    // <end_workflow_peek>
-}
diff --git a/docs/develop/java/clients.mdx b/docs/develop/java/clients.mdx
new file mode 100644
index 00000000..a58668a9
--- /dev/null
+++ b/docs/develop/java/clients.mdx
@@ -0,0 +1,113 @@
+---
+sidebar_position: 13
+description: "Use the clients to invoke handlers programmatically."
+---
+
+import Admonition from '@theme/Admonition';
+import {Step} from "../../../src/components/Stepper";
+
+# Clients
+The Restate SDK client library lets you invoke Restate handlers from anywhere in your application.
+Use this only in non-Restate services without access to the Restate Context.
+
+<Admonition type="note" title={"Use the Restate Context"}>
+    Always [invoke handlers via the context](/develop/java/service-communication), if you have access to it.
+    Restate then attaches information about the invocation to the parent invocation.
+</Admonition>
+
+## Invoking handlers with the SDK clients
+
+Invoke a handler programmatically with the SDK clients as follows:
+
+<Step stepLabel="1" title="Add the dependency to your project">
+    ```kotlin
+    implementation("dev.restate:sdk-common:VAR::TYPESCRIPT_SDK_VERSION")
+    ```
+</Step>
+<Step stepLabel="2" title={<span><a href={"/operate/registration"}>Register the service</a> you want to invoke.</span>}/>
+<Step stepLabel="3" title="Connect to Restate and invoke the handler with your preferred semantics">
+    <CH.Spotlight start={1} className="durable-promises">
+
+        ```java
+        CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_rpc_java>-<end_rpc_java>
+        ```
+
+        ---
+
+        **Request-response invocations** allow you to wait on a response from the handler.
+
+        ---
+
+        ```java
+        CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_one_way_call_java>-<end_one_way_call_java>
+        ```
+
+        **One-way invocations** allow you to send a message without waiting for a response.
+
+        ---
+
+        ```java
+        CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_delayed_call_java>-<end_delayed_call_java>
+        ```
+
+        **Delayed invocations** allow you to schedule an invocation for a later point in time.
+
+    </CH.Spotlight>
+</Step>
+
+<Admonition type="info" title="Invoking workflows">
+    [Have a look at the workflow documentation to learn what's different when invoking workflows.](/develop/java/workflows#submitting-workflows-with-sdk-clients)
+</Admonition>
+
+## Invoke a handler idempotently
+
+To make a service call idempotent, you can use the idempotency key feature.
+Add the idempotency key [to the header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) via:
+
+```java
+CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_service_idempotent>-<end_service_idempotent>
+```
+
+After the invocation completes, Restate persists the response for a retention period of one day (24 hours).
+If you re-invoke the service with the same idempotency key within 24 hours, Restate sends back the same response and doesn't re-execute the request to the service.
+
+<Admonition type="tip" title={"Make any service call idempotent by using Restate"}>
+    By using Restate and an idempotency key, you can make any service call idempotent, without any extra code or setup.
+    This is a very powerful feature to ensure that your system stays consistent and doesn't perform the same operation multiple times.
+</Admonition>
+
+<Admonition type="note" title={"Adding headers to the request"}>
+    The call options, with which we set the idempotency key, also let you add other headers to the request.
+</Admonition>
+
+<details className={"grey-details"}>
+    <summary> Tuning retention time</summary>
+
+    <CH.Section>
+        You can tune the [retention time](focus://3) on a service-level by using the [Admin API](focus://1[15:28]) ([docs](/references/admin-api#tag/service/operation/modify_service)):
+        ```shell
+        curl -X PATCH localhost:9070/services/MyService \
+            -H 'content-type: application/json' \
+            -d '{"idempotency_retention": "2days"}'
+        ```
+        The [retention time](focus://3) is in [humantime format](https://docs.rs/humantime/latest/humantime/).
+    </CH.Section>
+
+</details>
+
+## Retrieve result of invocations and workflows
+
+You can use the client library to retrieve the results of invocations **with an idempotency key** or workflows.
+You can:
+- Attach to an ongoing invocation and retrieve the result when it finishes.
+- Peek at the output of a running invocation or workflow, to check if it has finished and optionally retrieve the result.
+
+You can use the invocation ID to attach or peek at a service/object invocation that used an idempotency key:
+
+```java
+CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_service_attach>-<end_service_attach>
+```
+
+<Admonition type={"info"} title={"Attaching to workflows"}>
+    [Have a look at the workflow documentation to learn how to attach to workflow executions.](/develop/java/workflows#submitting-workflows-with-sdk-clients)
+</Admonition>
diff --git a/docs/develop/java/workflows.mdx b/docs/develop/java/workflows.mdx
index b3ac0d0c..9fc203cc 100644
--- a/docs/develop/java/workflows.mdx
+++ b/docs/develop/java/workflows.mdx
@@ -82,7 +82,7 @@ Have a look at the code example to get a better understanding of how workflows a
 ## Submitting workflows with SDK clients
 
 <CH.Spotlight className={"spotlight-medium"}>
-    [**Submit**](/invoke/clients?sdk=java#invoking-handlers-with-the-sdk-clients):
+    [**Submit**](/develop/java/clients):
     This returns a handle to the workflow once it has been registered in Restate.
     You can only submit once per workflow ID (here `"someone"`).
 
@@ -92,7 +92,7 @@ Have a look at the code example to get a better understanding of how workflows a
 </CH.Spotlight>
 
 <CH.Spotlight className={"spotlight-medium"}>
-    [**Query/signal**](/invoke/clients?sdk=java#invoking-handlers-with-the-sdk-clients):
+    [**Query/signal**](/develop/java/clients):
     Call the other handlers of the workflow in the same way as for Virtual Object handlers.
     Use `send()` for one-way calls.
 
@@ -103,15 +103,15 @@ Have a look at the code example to get a better understanding of how workflows a
 
 <CH.Spotlight className={"spotlight-medium"}>
 
-    [**Attach**](/invoke/clients?sdk=java#retrieve-result-of-invocations-and-workflows): This lets you retrieve the result of a workflow later.
+    [**Attach/peek**](/develop/java/clients#retrieve-result-of-invocations-and-workflows):
+    This lets you retrieve the result of a workflow or check if it's finished.
     Use `.getOutput()` to peek whether the result is ready.
-    
+
     ```java
     CODE_LOAD::java/src/main/java/develop/workflows/WorkflowSubmitter.java#<start_interact>-<end_interact>
     ```
 </CH.Spotlight>
 
-
 ## Submitting workflows from a Restate service
 
 <CH.Spotlight className={"spotlight-medium"}>
@@ -130,7 +130,7 @@ Have a look at the code example to get a better understanding of how workflows a
 ## Submitting workflows over HTTP
 
 <CH.Spotlight className={"spotlight-medium"}>
-    [**Submit/query/signal**](/invoke/http#request-response-calls-over-http):
+    [**Submit/query/signal**](/invoke/http):
     Call any handler of the workflow in the same way as for Services and Virtual Objects.
     This returns the result of the handler once it has finished.
     Add `/send` to the path for one-way calls.
@@ -145,8 +145,8 @@ Have a look at the code example to get a better understanding of how workflows a
 
 <CH.Spotlight className={"spotlight-medium"}>
 
-    [**Attach**](/invoke/http#retrieve-result-of-invocations-and-workflows):
-    This lets you retrieve the result of a workflow later.
+    [**Attach/peek**](/invoke/http#retrieve-result-of-invocations-and-workflows):
+    This lets you retrieve the result of a workflow or check if it's finished.
 
     ```shell
     curl localhost:8080/restate/workflow/SignupWorkflow/someone/attach
diff --git a/docs/develop/ts/clients.mdx b/docs/develop/ts/clients.mdx
new file mode 100644
index 00000000..5eb27219
--- /dev/null
+++ b/docs/develop/ts/clients.mdx
@@ -0,0 +1,108 @@
+---
+sidebar_position: 13
+description: "Use the clients to invoke handlers programmatically."
+---
+
+import Admonition from '@theme/Admonition';
+import {Step} from "../../../src/components/Stepper";
+
+# Clients
+
+The Restate SDK client library lets you invoke Restate handlers from anywhere in your application.
+Use this only in non-Restate services without access to the Restate Context.
+
+<Admonition type="note" title={"Use the Restate Context"}>
+Always [invoke handlers via the context](/develop/ts/service-communication), if you have access to it.
+Restate then attaches information about the invocation to the parent invocation.
+</Admonition>
+
+## Invoking handlers with the SDK clients
+
+<Step stepLabel="1" title="Add the dependency to your project">
+    ```shell
+    npm install @restatedev/restate-sdk-clients
+    ```
+</Step>
+<Step stepLabel="2" title={<span><a href={"/operate/registration"}>Register the service</a> you want to invoke.</span>}/>
+<Step stepLabel="3" title="Connect to Restate and invoke the handler with your preferred semantics">
+    <CH.Spotlight start={1} className="durable-promises">
+
+        ```typescript
+        CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_rpc_call_node>-<end_rpc_call_node>
+        ```
+
+        ---
+
+        **Request-response invocations** allow you to wait on a response from the handler.
+
+        ---
+
+        ```typescript
+        CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_one_way_call_node>-<end_one_way_call_node>
+        ```
+
+        **One-way invocations** allow you to send a message without waiting for a response.
+
+        ---
+
+        ```typescript
+        CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_delayed_call_node>-<end_delayed_call_node>
+        ```
+
+        **Delayed invocations** allow you to schedule an invocation for a later point in time.
+    </CH.Spotlight>
+</Step>
+
+<Admonition type="info" title="Invoking workflows">
+[Have a look at the workflow documentation to learn what's different when invoking workflows.](/develop/ts/workflows#submitting-workflows-with-sdk-clients)
+</Admonition>
+
+## Invoke a handler idempotently
+
+To make a service call idempotent, you can use the idempotency key feature.
+Add the idempotency key [to the header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) via:
+
+```typescript
+CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_service_idempotent>-<end_service_idempotent>
+```
+
+After the invocation completes, Restate persists the response for a retention period of one day (24 hours).
+If you re-invoke the service with the same idempotency key within 24 hours, Restate sends back the same response and doesn't re-execute the request to the service.
+
+<Admonition type="tip" title={"Make any service call idempotent by using Restate"}>
+    By using Restate and an idempotency key, you can make any service call idempotent, without any extra code or setup.
+    This is a very powerful feature to ensure that your system stays consistent and doesn't perform the same operation multiple times.
+</Admonition>
+
+<Admonition type="note" title={"Adding headers to the request"}>
+    The call options, with which we set the idempotency key, also let you add other headers to the request.
+</Admonition>
+
+<details className={"grey-details"}>
+    <summary> Tuning retention time</summary>
+
+    <CH.Section>
+        You can tune the [retention time](focus://3) on a service-level by using the [Admin API](focus://1[15:28]) ([docs](/references/admin-api#tag/service/operation/modify_service)):
+        ```shell
+        curl -X PATCH localhost:9070/services/MyService \
+            -H 'content-type: application/json' \
+            -d '{"idempotency_retention": "2days"}'
+        ```
+        The [retention time](focus://3) is in [humantime format](https://docs.rs/humantime/latest/humantime/).
+    </CH.Section>
+
+</details>
+
+## Retrieve result of invocations and workflows
+
+You can use the client library to retrieve the results of invocations **with an idempotency key** or workflows.
+
+Attach to them by using the handle that is returned from the invocation:
+
+```typescript
+CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_service_attach>-<end_service_attach>
+```
+
+<Admonition type={"info"} title={"Attaching to workflows"}>
+    [Have a look at the workflow documentation to learn how to attach to workflow executions.](/develop/ts/workflows#submitting-workflows-with-sdk-clients)
+</Admonition>
\ No newline at end of file
diff --git a/docs/develop/ts/workflows.mdx b/docs/develop/ts/workflows.mdx
index b973f1dc..e0948d7b 100644
--- a/docs/develop/ts/workflows.mdx
+++ b/docs/develop/ts/workflows.mdx
@@ -80,8 +80,8 @@ Have a look at the code example to get a better understanding of how workflows a
 ## Submitting workflows with SDK clients
 <CH.Spotlight className={"spotlight-medium"}>
 
-    [**Submit**](/invoke/clients#invoking-handlers-with-the-sdk-clients):
-    This returns when the workflow has been registered in Restate.
+    [**Submit**](/develop/ts/clients):
+    This returns a handle to the workflow once has been registered in Restate.
     You can only submit once per workflow ID (here `"someone"`).
 
     ```ts
@@ -91,7 +91,7 @@ Have a look at the code example to get a better understanding of how workflows a
 </CH.Spotlight>
 
 <CH.Spotlight className={"spotlight-medium"}>
-    [**Query/signal**](/invoke/clients#invoking-handlers-with-the-sdk-clients):
+    [**Query/signal**](/develop/ts/clients):
     Call the other handlers of the workflow in the same way as for Virtual Object handlers.
     For now, you can only do request-response calls.
 
@@ -102,7 +102,8 @@ Have a look at the code example to get a better understanding of how workflows a
 
 <CH.Spotlight className={"spotlight-medium"}>
 
-    [**Attach**](/invoke/clients#retrieve-result-of-invocations-and-workflows): This lets you retrieve the result of a workflow later.
+    [**Attach/peek**](/develop/ts/clients#retrieve-result-of-invocations-and-workflows):
+    This lets you retrieve the result of a workflow or check if it's finished.
 
     ```ts
     CODE_LOAD::ts/src/develop/workflows/submit.ts#<start_attach>-<end_attach>
@@ -140,8 +141,8 @@ Have a look at the code example to get a better understanding of how workflows a
 
 <CH.Spotlight className={"spotlight-medium"}>
 
-    [**Attach**](/invoke/http#retrieve-result-of-invocations-and-workflows):
-    This lets you retrieve the result of a workflow later.
+    [**Attach/peek**](/invoke/http#retrieve-result-of-invocations-and-workflows):
+    This lets you retrieve the result of a workflow or check if it's finished.
 
     ```shell
     curl localhost:8080/restate/workflow/signup/someone/attach
diff --git a/docs/invoke/clients.mdx b/docs/invoke/clients.mdx
index 8246067f..94b9b546 100644
--- a/docs/invoke/clients.mdx
+++ b/docs/invoke/clients.mdx
@@ -3,241 +3,34 @@ sidebar_position: 2
 description: "Use the clients to invoke handlers programmatically."
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
 import Admonition from '@theme/Admonition';
-import {Step} from "../../src/components/Stepper";
+import FeatureWidget from "../../src/components/FeatureWidget";
 
 # Clients
-When you implement a Restate handler, you have access to a Restate `Context`.
-You can use this context to invoke other handlers.
-Have a look at the Development docs ([TS](/develop/ts/service-communication)/[Java](/develop/java/service-communication)/[Kotlin](/develop/java/service-communication?sdk=kotlin)).
-
-In plain TypeScript/Java/Kotlin code, where you do not have access to the Restate Context, you can invoke handlers programmatically using the Restate SDK client library.
+The Restate SDK client library lets you invoke Restate handlers from anywhere in your application.
+Use this only in non-Restate services without access to the Restate Context.
 
 <Admonition type="note" title={"Use the Restate Context"}>
-Always invoke handlers via the context, if you have access to it.
-Restate then attaches information about the invocation to the parent invocation.
-</Admonition>
-
-## Invoking handlers with the SDK clients
-
-Invoke a handler programmatically with the SDK clients as follows:
-
-<Tabs groupId="sdk" queryString>
-    <TabItem value="ts" label="TypeScript">
-        <Step stepLabel="1" title="Add the dependency to your project">
-            ```shell
-            npm install @restatedev/restate-sdk-clients
-            ```
-        </Step>
-        <Step stepLabel="2" title={<span><a href={"/operate/registration"}>Register the service</a> you want to invoke.</span>}/>
-        <Step stepLabel="3" title="Connect to Restate and invoke the handler with your preferred semantics">
-            <CH.Spotlight start={1} className="durable-promises">
-
-                ```typescript
-                CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_rpc_call_node>-<end_rpc_call_node>
-                ```
-
-                ---
-
-                **Request-response invocations** allow you to wait on a response from the handler.
-
-                ---
-
-                ```typescript
-                CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_one_way_call_node>-<end_one_way_call_node>
-                ```
-
-                **One-way invocations** allow you to send a message without waiting for a response.
-
-                ---
-
-                ```typescript
-                CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_delayed_call_node>-<end_delayed_call_node>
-                ```
-
-                **Delayed invocations** allow you to schedule an invocation for a later point in time.
-            </CH.Spotlight>
-        </Step>
-    </TabItem>
-    <TabItem value="java" label="Java">
-        <Step stepLabel="1" title="Add the dependency to your project">
-            ```kotlin
-            implementation("dev.restate:sdk-common:VAR::TYPESCRIPT_SDK_VERSION")
-            ```
-        </Step>
-        <Step stepLabel="2" title={<span><a href={"/operate/registration"}>Register the service</a> you want to invoke.</span>}/>
-        <Step stepLabel="3" title="Connect to Restate and invoke the handler with your preferred semantics">
-            <CH.Spotlight start={1} className="durable-promises">
-
-                ```java
-                CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_rpc_java>-<end_rpc_java>
-                ```
-
-                ---
-
-                **Request-response invocations** allow you to wait on a response from the handler.
-
-                ---
-
-                ```java
-                CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_one_way_call_java>-<end_one_way_call_java>
-                ```
-
-                **One-way invocations** allow you to send a message without waiting for a response.
-
-                ---
-
-                ```java
-                CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_delayed_call_java>-<end_delayed_call_java>
-                ```
-
-                **Delayed invocations** allow you to schedule an invocation for a later point in time.
-
-            </CH.Spotlight>
-        </Step>
-    </TabItem>
-</Tabs>
-
-<Admonition type={"tip"} title={"Retrieve results of one-way invocations and workflows"}>
-    You can retrieve the results of one-way invocations with an idempotency key and workflows, as [described here](/invoke/clients#retrieve-result-of-invocations-and-workflows).
-</Admonition>
-
-## Invoke a handler idempotently
-
-To make a service call idempotent, you can use the idempotency key feature.
-Add the idempotency key [to the header](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/) via:
-
-<Tabs groupId="sdk" queryString>
-    <TabItem value="ts" label="TypeScript">
-
-        ```typescript
-        CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_service_idempotent>-<end_service_idempotent>
-        ```
-
-    </TabItem>
-    <TabItem value="java" label="Java">
-
-        ```java
-        CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_service_idempotent>-<end_service_idempotent>
-        ```
-
-    </TabItem>
-</Tabs>
-
-
-
-After the invocation completes, Restate persists the response for a retention period of one day (24 hours).
-If you re-invoke the service with the same idempotency key within 24 hours, Restate sends back the same response and doesn't re-execute the request to the service.
-
-<Admonition type="tip" title={"Make any service call idempotent by using Restate"}>
-    By using Restate and an idempotency key, you can make any service call idempotent, without any extra code or setup.
-    This is a very powerful feature to ensure that your system stays consistent and doesn't perform the same operation multiple times.
+    Always [invoke handlers via the context](/develop/java/service-communication), if you have access to it.
+    Restate then attaches information about the invocation to the parent invocation.
 </Admonition>
 
-<Admonition type="note" title={"Adding headers to the request"}>
-    The call options, with which we set the idempotency key, also let you add other headers to the request.
-</Admonition>
-
-<details className={"grey-details"}>
-    <summary> Tuning retention time</summary>
-
-    <CH.Section>
-        You can tune the [retention time](focus://3) on a service-level by using the [Admin API](focus://1[15:28]) ([docs](/references/admin-api#tag/service/operation/modify_service)):
-        ```shell
-        curl -X PATCH localhost:9070/services/MyService \
-            -H 'content-type: application/json' \
-            -d '{"idempotency_retention": "2days"}'
-        ```
-        The [retention time](focus://3) is in [humantime format](https://docs.rs/humantime/latest/humantime/).
-    </CH.Section>
-
-</details>
-
-## Retrieve result of invocations and workflows
-
-You can use the client library to retrieve the results of invocations with an idempotency key or workflows.
-You can:
-- Attach to an ongoing invocation and retrieve the result when it finishes.
-- Peek at the output of a running invocation or workflow, to check if it has finished and optionally retrieve the result.
-
-You can attach to a service/object invocation only if the invocation used an idempotency key.
-
-<Tabs groupId="sdk" queryString>
-    <TabItem value="ts" label="TypeScript">
-
-<CH.Spotlight start={1} className={"workflows-scroller-large"}>
-
-    ```typescript
-    CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_service_attach>-<end_service_attach>
-    ```
-
-    ---
-
-    **Attach to service/object calls** by using the handle that is returned from the invocation.
-
-    ```typescript
-    CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_service_attach>-<end_service_attach>
-    ```
-
-    ---
-
-    **Attach to workflows** by using the handle that is returned from the invocation, or by using the workflow ID.
-
-    ```typescript
-    CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_workflow_attach>-<end_workflow_attach>
-    ```
-
-    ---
-
-    **Peek at the output of workflows** by using the workflow ID.
-
-    ```typescript
-    CODE_LOAD::ts/src/operate/invocations/ingress.ts#<start_workflow_peek>-<end_workflow_peek>
-    ```
-
-</CH.Spotlight>
-
-</TabItem>
-<TabItem value="java" label="Java">
-<CH.Spotlight start={1}>
-    ```java
-    CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_service_attach>-<end_service_attach>
-    ```
-
-    ---
-
-    **Attach to service/object calls** by using the handle that is returned from the invocation.
-
-    ```java
-    CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_service_attach>-<end_service_attach>
-    ```
-
-    ---
-
-    **Peek at the output of service/object calls** by using the handle that is returned from the invocation.
-
-    ```java
-    CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_service_peek>-<end_service_peek>
-    ```
-
-    ---
-
-    **Attach to workflows** by using the handle that is returned from the invocation, or by using the workflow ID.
-
-    ```java
-    CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_workflow_attach>-<end_workflow_attach>
-    ```
-
-    ---
-
-    **Peek at the output of workflows** by using the workflow ID.
-
-    ```java
-    CODE_LOAD::java/src/main/java/operate/invocations/Ingress.java#<start_workflow_peek>-<end_workflow_peek>
-    ```
-</CH.Spotlight>
-</TabItem>
-</Tabs>
+Have a look at the documentation of the SDKs:
+
+<FeatureWidget features={
+    [
+        {
+            title: "Invoking Services/Virtual Objects",
+            description: "with the SDK clients",
+            java: "/develop/java/clients",
+            ts: "/develop/ts/clients"
+        },
+        {
+            title: "Invoking Workflows",
+            description: "with the SDK clients",
+            java: "/develop/java/workflows",
+            ts: "/develop/ts/workflows"
+        }
+    ]
+}/>
 
diff --git a/docs/invoke/http.mdx b/docs/invoke/http.mdx
index 94a99cb6..bb2fcb4d 100644
--- a/docs/invoke/http.mdx
+++ b/docs/invoke/http.mdx
@@ -82,11 +82,6 @@ curl localhost:8080/MyService/myHandler/send \
 The response contains the [Invocation ID](/operate/invocation#invocation-identifier).
 You can use this identifier [to cancel](/operate/invocation#cancelling-invocations) or [kill the invocation](/operate/invocation#killing-invocations).
 
-<Admonition type={"tip"} title={"Retrieving results of one-way invocations and workflows"}>
-    You can retrieve the results of one-way invocations with an idempotency key and workflows, as [described here](/invoke/clients#retrieve-result-of-invocations-and-workflows).
-</Admonition>
-
-
 ## Sending a delayed message over HTTP
 
 You can **delay the message** by adding a delay request parameter in ISO8601 notation or in seconds:
@@ -161,48 +156,24 @@ There are two options:
   - The result for finished workflows
   - `{"message":"not found"}` for non-existing workflows
 
-You can attach to a service/object invocation only if the invocation used an idempotency key.
-
-<CH.Spotlight start={1} className="durable-promises">
-
-    ```shell
-    curl localhost:8080/restate/invocation/myInvocationId/attach
-    curl localhost:8080/restate/invocation/myInvocationId/output
-    ```
-
-    ---
-
-    Via invocation ID
-
-    ```shell
-    curl localhost:8080/restate/invocation/myInvocationId/attach
-    curl localhost:8080/restate/invocation/myInvocationId/output
-    ```
-    ---
-
-    ```shell
-    curl localhost:8080/restate/invocation/MyService/myHandler/myIdempotencyKey/attach
-    curl localhost:8080/restate/invocation/MyService/myHandler/myIdempotencyKey/output
-    ```
-
-    For Services, via [idempotency key](/invoke/http#invoke-a-handler-idempotently)
-
-    ---
+You can attach to a service/object invocation only if the invocation used an idempotency key:
 
-    ```shell
-    curl localhost:8080/restate/invocation/myObject/myKey/myHandler/myIdempotencyKey/attach
-    curl localhost:8080/restate/invocation/myObject/myKey/myHandler/myIdempotencyKey/output
-    ```
+```shell
+# Via invocation ID
+curl localhost:8080/restate/invocation/myInvocationId/attach
+curl localhost:8080/restate/invocation/myInvocationId/output
 
-    For Virtual Objects, via [idempotency key](/invoke/http#invoke-a-handler-idempotently)
+# For Services, via idempotency key
+curl localhost:8080/restate/invocation/MyService/myHandler/myIdempotencyKey/attach
+curl localhost:8080/restate/invocation/MyService/myHandler/myIdempotencyKey/output
 
-    ---
+# For Virtual Objects, via idempotency key
+curl localhost:8080/restate/invocation/myObject/myKey/myHandler/myIdempotencyKey/attach
+curl localhost:8080/restate/invocation/myObject/myKey/myHandler/myIdempotencyKey/output
 
-    ```shell
-    curl localhost:8080/restate/workflow/MyWorkflow/myWorkflowId/attach
-    curl localhost:8080/restate/workflow/MyWorkflow/myWorkflowId/output
-    ```
+# For Workflows, with the Workflow ID
+curl localhost:8080/restate/workflow/MyWorkflow/myWorkflowId/attach
+curl localhost:8080/restate/workflow/MyWorkflow/myWorkflowId/output
+```
 
-    For Workflows, with the Workflow ID
 
-</CH.Spotlight>