diff --git a/akka-docs/src/main/paradox/typed/persistence.md b/akka-docs/src/main/paradox/typed/persistence.md
index b42891d844..0848ffc6f3 100644
--- a/akka-docs/src/main/paradox/typed/persistence.md
+++ b/akka-docs/src/main/paradox/typed/persistence.md
@@ -50,8 +50,7 @@ Next we'll discuss each of these in detail.
 
 ### Command handler
 
-The command handler is a function with @java[2 parameters for]@scala[3 parameters for the `ActorContext`,]
-current `State` and `Command`.
+The command handler is a function with 2 parameters, the current `State` and the incoming `Command`.
 
 A command handler returns an `Effect` directive that defines what event or events, if any, to persist. 
 Effects are created using @java[a factory that is returned via the `Effect()` method] @scala[the `Effect` factory]
@@ -127,7 +126,18 @@ Java
 
 The `PersistentBehavior` can then be run as with any plain typed actor as described in [typed actors documentation](actors-typed.md).
 
-@java[The `ActorContext` can be obtained with `Behaviors.setup` and be passed as a constructor parameter.]
+
+## Accessing the ActorContext
+
+If the persistent behavior needs to use the `ActorContext`, for example to spawn child actors, it can be obtained by 
+wrapping construction with `Behaviors.setup`:
+
+Scala
+:  @@snip [PersistentActorCompileOnyTest.scala](/akka-persistence-typed/src/test/scala/akka/persistence/typed/scaladsl/PersistentActorCompileOnlyTest.scala) { #actor-context }
+
+Java
+:  @@snip [PersistentActorCompileOnyTest.java](/akka-persistence-typed/src/test/java/akka/persistence/typed/javadsl/PersistentActorCompileOnlyTest.java) { #actor-context }
+
 
 
 ## Larger example
diff --git a/akka-persistence-typed/src/test/java/akka/persistence/typed/javadsl/PersistentActorCompileOnlyTest.java b/akka-persistence-typed/src/test/java/akka/persistence/typed/javadsl/PersistentActorCompileOnlyTest.java
index 62d5d82f57..3667055446 100644
--- a/akka-persistence-typed/src/test/java/akka/persistence/typed/javadsl/PersistentActorCompileOnlyTest.java
+++ b/akka-persistence-typed/src/test/java/akka/persistence/typed/javadsl/PersistentActorCompileOnlyTest.java
@@ -5,8 +5,10 @@
 package akka.persistence.typed.javadsl;
 
 import akka.actor.Scheduler;
+import akka.actor.typed.Behavior;
 import akka.actor.typed.javadsl.ActorContext;
 import akka.actor.typed.ActorRef;
+import akka.actor.typed.javadsl.Behaviors;
 import akka.persistence.typed.EventAdapter;
 import akka.actor.testkit.typed.javadsl.TestInbox;
 import akka.persistence.typed.SideEffect;
@@ -266,13 +268,24 @@ public class PersistentActorCompileOnlyTest {
         .thenAccept(sender::tell);
     }
 
+    // #actor-context
+    public Behavior<Command> behavior(String persistenceId) {
+      return Behaviors.setup(ctx -> new MyPersistentBehavior(persistenceId, ctx));
+    }
+
+    // #actor-context
+
+    // #actor-context
     class MyPersistentBehavior extends PersistentBehavior<Command, Event, RecoveryComplete.EventsInFlight> {
+
+      // this makes the context available to the command handler etc.
       private final ActorContext<Command> ctx;
 
       public MyPersistentBehavior(String persistenceId, ActorContext<Command> ctx) {
         super(persistenceId);
         this.ctx = ctx;
       }
+      // #actor-context
 
       @Override
       public EventsInFlight emptyState() {
@@ -307,4 +320,5 @@ public class PersistentActorCompileOnlyTest {
       }
     }
   }
+
 }
diff --git a/akka-persistence-typed/src/test/scala/akka/persistence/typed/scaladsl/PersistentActorCompileOnlyTest.scala b/akka-persistence-typed/src/test/scala/akka/persistence/typed/scaladsl/PersistentActorCompileOnlyTest.scala
index f35e901bba..31332db44d 100644
--- a/akka-persistence-typed/src/test/scala/akka/persistence/typed/scaladsl/PersistentActorCompileOnlyTest.scala
+++ b/akka-persistence-typed/src/test/scala/akka/persistence/typed/scaladsl/PersistentActorCompileOnlyTest.scala
@@ -432,4 +432,31 @@ object PersistentActorCompileOnlyTest {
 
   }
 
+
+  object WithContext {
+    sealed trait Command
+    sealed trait Event
+    class State
+
+    // #actor-context
+    val behavior: Behavior[String] =
+      Behaviors.setup { ctx =>
+        PersistentBehaviors.receive[String, String, State](
+          persistenceId = "myPersistenceId",
+          emptyState = new State,
+          commandHandler = CommandHandler.command {
+            cmd ⇒
+              ctx.log.info("Got command {}", cmd)
+              Effect.persist(cmd).thenRun { state =>
+                ctx.log.info("event persisted, new state {}", state)
+              }
+          },
+          eventHandler = {
+            case (state, _) ⇒ state
+          })
+      }
+    // #actor-context
+
+  }
+
 }