diff --git a/docs/best-practices.md b/docs/best-practices.md
index da60095..b717544 100644
--- a/docs/best-practices.md
+++ b/docs/best-practices.md
@@ -343,7 +343,7 @@ context.create_callback(name="payment_callback")
 context.create_callback(name="approval_callback")
 
 # Pattern: descriptive_wait for waits
-context.wait(seconds=30, name="payment_confirmation_wait")
+context.wait(Duration.from_seconds(30), name="payment_confirmation_wait")
 ```
 
 ### Name dynamic operations with context
@@ -494,7 +494,7 @@ Only use waits when you need to delay execution:
 @durable_execution
 def lambda_handler(event: dict, context: DurableContext) -> dict:
     job_id = context.step(start_job(event["data"]))
-    context.wait(seconds=30, name="job_processing_wait")  # Necessary
+    context.wait(Duration.from_seconds(30), name="job_processing_wait")  # Necessary
     result = context.step(check_job_status(job_id))
     return result
 ```
@@ -609,7 +609,7 @@ def lambda_handler(event: dict, context: DurableContext) -> dict:
 @durable_step
 def process_with_wait(step_context: StepContext, context: DurableContext) -> str:
     # DON'T: Can't use context inside its own step operation
-    context.wait(seconds=1)  # Error: using context inside step!
+    context.wait(Duration.from_seconds(1))  # Error: using context inside step!
     result = context.step(nested_step(), name="step2")  # Error: nested context.step!
     return result
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 3854293..69b9c15 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -72,7 +72,7 @@ def handler(event: dict, context: DurableContext) -> dict:
     data = context.step(fetch_data(event["id"]))
     
     # Step 2: Wait 30 seconds
-    context.wait(seconds=30)
+    context.wait(Duration.from_seconds(30))
     
     # Step 3: Process the data
     result = context.step(process_data(data))
@@ -85,7 +85,7 @@ def handler(event: dict, context: DurableContext) -> dict:
 1. Lambda invokes your function
 2. `fetch_data` executes and calls an external API
 3. Result is checkpointed to AWS
-4. `context.wait(seconds=30)` is reached
+4. `context.wait(Duration.from_seconds(30))` is reached
 5. Function returns, Lambda can recycle the environment
 
 **Second invocation (t=30s):**
@@ -93,7 +93,7 @@ def handler(event: dict, context: DurableContext) -> dict:
 1. Lambda invokes your function again
 2. Function code runs from the beginning
 3. `fetch_data` returns the checkpointed result instantly (no API call)
-4. `context.wait(seconds=30)` is already complete, execution continues
+4. `context.wait(Duration.from_seconds(30))` is already complete, execution continues
 5. `process_data` executes for the first time
 6. Result is checkpointed
 7. Function returns the final result
diff --git a/docs/index.md b/docs/index.md
index 603d02d..60109df 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -55,6 +55,7 @@ from aws_durable_execution_sdk_python import (
     durable_execution,
     durable_step,
 )
+from aws_durable_execution_sdk_python.config import Duration
 
 @durable_step
 def validate_order(order_id: str) -> dict:
@@ -86,7 +87,7 @@ def process_order(event: dict, context: DurableContext) -> dict:
     payment = context.step(charge_payment(order_id, amount))
     
     # Step 3: Wait for payment confirmation (simulated)
-    context.wait(seconds=5)
+    context.wait(Duration.from_seconds(5))
     
     # Step 4: Fulfill the order
     fulfillment = context.step(fulfill_order(order_id))
diff --git a/docs/testing-patterns/basic-tests.md b/docs/testing-patterns/basic-tests.md
index ceccddc..fc09908 100644
--- a/docs/testing-patterns/basic-tests.md
+++ b/docs/testing-patterns/basic-tests.md
@@ -311,10 +311,11 @@ Here's a function with a wait:
 
 ```python
 from aws_durable_execution_sdk_python import DurableContext, durable_execution
+from aws_durable_execution_sdk_python.config import Duration
 
 @durable_execution
 def handler(event: dict, context: DurableContext) -> str:
-    context.wait(seconds=5)
+    context.wait(Duration.from_seconds(5))
     return "Wait completed"
 ```
 
diff --git a/docs/testing-patterns/complex-workflows.md b/docs/testing-patterns/complex-workflows.md
index 9cb50b6..6781b06 100644
--- a/docs/testing-patterns/complex-workflows.md
+++ b/docs/testing-patterns/complex-workflows.md
@@ -121,7 +121,7 @@ def handler(event: dict, context: DurableContext) -> str:
     
     if amount > 1000:
         context.step(lambda _: "Manager approval required", name="approval")
-        context.wait(seconds=10, name="approval_wait")
+        context.wait(Duration.from_seconds(10), name="approval_wait")
         result = context.step(lambda _: "High-value order processed", name="process_high")
     else:
         result = context.step(lambda _: "Standard order processed", name="process_standard")
@@ -514,7 +514,7 @@ For workflows with long waits, verify configuration without actually waiting:
 @durable_execution
 def handler(event: dict, context: DurableContext) -> str:
     context.step(lambda _: "Starting", name="start")
-    context.wait(seconds=3600, name="long_wait")  # 1 hour
+    context.wait(Duration.from_seconds(3600), name="long_wait")  # 1 hour
     context.step(lambda _: "Continuing", name="continue")
     return "Complete"
 ```
@@ -559,7 +559,7 @@ def handler(event: dict, context: DurableContext) -> int:
         if state >= 3:
             break
         
-        context.wait(seconds=1, name=f"wait_{attempt}")
+        context.wait(Duration.from_seconds(1), name=f"wait_{attempt}")
     
     return state
 ```
@@ -604,7 +604,7 @@ def handler(event: dict, context: DurableContext) -> dict:
         state = context.step(lambda _, s=state: s + 1, name=f"attempt_{attempt}")
         
         if state < target:
-            context.wait(seconds=1, name=f"wait_{attempt}")
+            context.wait(Duration.from_seconds(1), name=f"wait_{attempt}")
     
     return {"state": state, "attempts": attempt, "reached_target": state >= target}
 ```