fix: docs2markdown.sh and other improvements

docs/bin/docs2markdown.sh

@@ -20,10 +20,12 @@ find target/site \
   -exec sh -c 'npx -y d2m@latest -e -i "$1" -o "$1.md"' sh {} \;
 
 # replace numbered references in code snippets
+# Only match callout numbers at end of line (preceded by space) to avoid
+# breaking code arguments like Counter(0), ofSeconds(30), invoke(10)
 if [[ "$OSTYPE" == "darwin"* ]]; then
-  find target/site -type f -name "*.html.md" -print0 | xargs -0 sed -i '' -E 's/\(([0-9]+)\)/\/\/ (\1)/g'
+  find target/site -type f -name "*.html.md" -print0 | xargs -0 sed -i '' -E 's/ \(([0-9]+)\)$/ \/\/ (\1)/g'
 else
-  find target/site -type f -name "*.html.md" -print0 | xargs -0 sed -i -E 's/\(([0-9]+)\)/\/\/ (\1)/g'
+  find target/site -type f -name "*.html.md" -print0 | xargs -0 sed -i -E 's/ \(([0-9]+)\)$/ \/\/ (\1)/g'
 fi
 
 cp docs/src/modules/ROOT/pages/llms.txt target/site/

docs/src/modules/operations/pages/cli/using-cli.adoc

@@ -122,7 +122,7 @@ Required flags:
 * `--docker-username` (your Docker username)
 * `--docker-password` (your Docker password)
 
-TODO:  For more details, see `akka docker -h` or visit xref:reference:cli/akka-cli/akka_docker.adoc[docker] page.
+For more details, see `akka docker -h` or visit the xref:reference:cli/akka-cli/akka_docker.adoc[docker] page.
 [NOTE]
 ====
 For more information about using the Akka Container Registry (ACR) or external container registries, see xref:projects/container-registries.adoc[].
@@ -204,7 +204,7 @@ This table shows the component names, their types, and any associated type IDs.
 
 [TIP]
 ====
-If you want to view the events from an event sourced entity you can use the `akka service components list-events` command.
+If you want to view the events from an event sourced entity you can use the `akka services components list-events` command.
 
 More information about this command in xref:reference:cli/akka-cli/akka_services_components_list-events.adoc[components] page.
 ====

docs/src/modules/operations/pages/projects/broker-aiven.adoc

@@ -34,7 +34,7 @@ akka config get-project
 akka secret create tls-ca kafka-ca-cert --cert ./ca.pem
 ----
 
-. Copy the CA password from the "Connection Information" and store it in an Akka secret (e.g. called `kafka-secret`)
+. Copy the SASL password from the "Connection Information" and store it in an Akka secret (e.g. called `kafka-secret`)
 +
 [source, command window]
 ----
@@ -76,7 +76,7 @@ Browser::
 Instructions from Aiven's https://docs.aiven.io/docs/products/kafka/howto/create-topic[Creating an Apache Kafka topic, window="new"]
 
 . Open the https://console.aiven.io/[Aiven Console, window="new"].
-. In the Services page, click on the Aiven for Apache Kafka® service where you want to crate the topic.
+. In the Services page, click on the Aiven for Apache Kafka® service where you want to create the topic.
 . Select the Topics tab:
 .. In the Add new topic section, enter a name for your topic.
 .. In the Advanced configuration you can set the replication factor, number of partitions and other advanced settings. These can be modified later.

docs/src/modules/operations/pages/projects/broker-aws-msk.adoc

@@ -12,7 +12,7 @@ with a user and password to use for authenticating your Akka service
 
 .. The user and password is stored in a secret
 
-.. The secret must be encrypted with a specific key, MSK cannot use the default MKS encryption key
+.. The secret must be encrypted with a specific key, MSK cannot use the default MSK encryption key
 
 . The provisioned cluster must be set up for https://docs.aws.amazon.com/msk/latest/developerguide/public-access.html[public access, window="new"]
 
@@ -51,10 +51,10 @@ akka projects config set broker  \
   --broker-auth scram-sha-512 \
   --broker-user <sasl username> \
   --broker-password-secret aws-msk-secret/pwd \
-  --broker-bootstrap-servers <bootstrap brokers> \
+  --broker-bootstrap-servers <bootstrap brokers>
 ----
 
-The `broker-password-secret` refer to the name of the Akka secret created earlier rather than the actual password string.
+The `broker-password-secret` refers to the name of the Akka secret created earlier rather than the actual password string.
 
 An optional description can be added with the parameter `--description` to provide additional notes about the broker.
 
@@ -84,8 +84,8 @@ akka projects config set broker  \
   --broker-auth scram-sha-512 \
   --broker-user <sasl username> \
   --broker-password-secret aws-msk-secret/pwd \
-  --broker-ca-cert-secret kafka-ca-cert
-  --broker-bootstrap-servers <bootstrap brokers> \
+  --broker-ca-cert-secret kafka-ca-cert \
+  --broker-bootstrap-servers <bootstrap brokers>
 ----
 
 

docs/src/modules/sdk/pages/event-sourced-entities.adoc

@@ -122,8 +122,8 @@ As mentioned above, the business logic for updating the state was placed on the
 include::example$shopping-cart-quickstart/src/main/java/shoppingcart/domain/ShoppingCart.java[tag=addItem]
 ----
 <1> For an existing item, we will make sure to sum the existing quantity with the incoming one.
-<2> Returns an update list of items without the existing item.
-<3> Adds the update item to the shopping cart.
+<2> Returns an updated list of items without the existing item.
+<3> Adds the updated item to the shopping cart.
 <4> Returns a new instance of the shopping cart with the updated line items.
 
 
@@ -137,7 +137,7 @@ To have access to the current state of the entity we can use `currentState()` as
 include::example$shopping-cart-quickstart/src/main/java/shoppingcart/application/ShoppingCartEntity.java[tag=getCart]
 ----
 <1> Stores the `entityId` on an internal attribute so we can use it later.
-<2> Provides initial state - overriding `emptyState()` is optional but if not doing it, be careful to deal with a `currentState()` with a `null` value when receiving the first command or event.
+<2> Provides initial state - we recommend always overriding `emptyState()` to return a sensible default. If not overridden, `currentState()` will return `null` until the first event is persisted, which requires null checks in all command and event handlers.
 <3> Returns the current state as reply for the request.
 
 IMPORTANT: We are returning the internal state directly back to the requester. In the endpoint, it's usually best to convert this internal domain model into a public model so the internal representation is free to evolve without breaking clients code.
@@ -266,7 +266,7 @@ WARNING: Notifications should not be used for building business logic. Akka does
 
 == Side effects
 
-An entity doesn't perform any external side effects aside from persisting events and replying to the request. Side effects can be handled from the Workflow, Consumer, or Endpoint components that are calling the entity.
+An entity doesn't perform any external side effects aside from persisting events, replying to the request, and publishing notifications. Other side effects, such as calling external services or other components, should be handled from the Workflow, Consumer, or Endpoint components that are calling the entity.
 
 == Testing the entity
 
@@ -284,13 +284,13 @@ include::example$shopping-cart-quickstart/src/test/java/shoppingcart/application
 ----
 <1> Creates the TestKit passing the constructor of the Entity.
 <2> Calls the method `addItem` from the Entity in the `EventSourcedTestKit` with quantity `10`.
-<3> Asserts the return value is `"OK"`.
-<4> Returns the next event of type `IdemAdded` and asserts on the quantity.
+<3> Asserts the return value is `Done`.
+<4> Returns the next event of type `ItemAdded` and asserts on the quantity.
 <5> Add a new item with quantity `5`.
 <6> Asserts that the total number of events should be 2.
 <7> Calls the `getCart` method and asserts that quantity should be `15`.
 
-NOTE: The `EventSourcedTestKit` is stateful, and it holds the state of a single entity instance in memory. If you want to test more than one entity in a test, you need to create multiple instance of `EventSourcedTestKit`.
+NOTE: The `EventSourcedTestKit` is stateful, and it holds the state of a single entity instance in memory. If you want to test more than one entity in a test, you need to create multiple instances of `EventSourcedTestKit`.
 
 *EventSourcedResult*
 
@@ -320,9 +320,9 @@ include::example$shopping-cart-quickstart/src/test/java/shoppingcart/ShoppingCar
 ----
 <1> Note the test class must extend `TestKitSupport`.
 <2> A built-in component client is provided to interact with the components.
-<3> Request to create a new shopping cart with id `cart-abc`.
-<4> Request to add an item to the cart.
-<5> Request to retrieve current status of the shopping cart.
-<6> Assert there should only be one item.
+<3> Identify the entity instance by its id `cart-abc`.
+<4> Call the `addItem` command handler on the entity.
+<5> Retrieve the current shopping cart state.
+<6> Assert there should only be one item remaining after removal.
 
 NOTE: The integration tests in samples can be run using `mvn verify`.

docs/src/modules/sdk/pages/key-value-entities.adoc

@@ -54,7 +54,7 @@ For additional details, refer to xref:concepts:declarative-effects.adoc[Declarat
 
 Now that we have our Entity state defined, the remaining steps can be summarized as follows:
 
-- Declare your entity and pick an entity id (it needs to be a unique identifier).
+- Declare your entity and pick a component id (it needs to be a unique identifier).
 - Initialize your entity state
 - Implement how each command is handled.
 
@@ -100,7 +100,7 @@ include::example$key-value-counter/src/main/java/com/example/application/Counter
 ----
 <1> Reply with the current state.
 
-What if this is the first command we are receiving for this entity? The initial state is provided by overriding `emptyState()`. That is optional and if not doing it, be careful to deal with a `currentState()` with a `null` value when receiving the first command.
+What if this is the first command we are receiving for this entity? The initial state is provided by overriding `emptyState()`. We recommend always overriding `emptyState()` to return a sensible default. If not overridden, `currentState()` will return `null` until the first state update, which requires null checks in all command handlers.
 
 IMPORTANT: We are returning the internal state directly back to the requester. In the endpoint, it's usually best to convert this internal domain model into a public model so the internal representation is free to evolve without breaking clients code.
 
@@ -147,7 +147,7 @@ include::partial$mutli-region-replication.adoc[]
 The state of the entity is by default replicated to all regions that have been enabled for the service. For regulatory reasons or as cost optimization it is possible to filter which regions that participate in the replication for a specific entity. This can be changed at runtime by the entity itself.
 
 [source,java]
-.Counter.java
+.CounterEntity.java
 ----
 include::example$doc-snippets/src/main/java/com/example/replicationfilter/CounterEntity.java[tag=replication-filter]
 ----
@@ -215,15 +215,15 @@ WARNING: Notifications should not be used for building business logic. Akka does
 
 == Side effects
 
-An entity doesn't perform any external side effects aside from persisting state changes and replying to the request. Side effects can be handled from the Workflow, Consumer, or Endpoint components that are calling the entity.
+An entity doesn't perform any external side effects aside from persisting state changes, replying to the request, and publishing notifications. Other side effects, such as calling external services or other components, should be handled from the Workflow, Consumer, or Endpoint components that are calling the entity.
 
 == Testing the entity
 
 include::partial$testing-entity.adoc[]
 
 === Unit tests
 
-The following snippet shows how the `KeyValueEntityTestKit` is used to test the `CountertEntity` implementation. Akka provides two main APIs for unit tests, the `KeyValueEntityTestKit` and the `KeyValueEntityResult`. The former gives us the overall state of the entity and the ability to call the command handlers while the latter only holds the effects produced for each individual call to the Entity.
+The following snippet shows how the `KeyValueEntityTestKit` is used to test the `CounterEntity` implementation. Akka provides two main APIs for unit tests, the `KeyValueEntityTestKit` and the `KeyValueEntityResult`. The former gives us the overall state of the entity and the ability to call the command handlers while the latter only holds the effects produced for each individual call to the Entity.
 
 [source,java,indent=0]
 .{sample-base-url}/key-value-counter/src/test/java/com/example/CounterTest.java[CounterTest.java]
@@ -236,7 +236,7 @@ include::example$key-value-counter/src/test/java/com/example/CounterTest.java[ta
 <4> Calls the method `plusOne` from the Entity in the `KeyValueEntityTestKit` and assert reply value of `11`.
 <5> Asserts the state value after both operations is `11`.
 
-NOTE: The `KeyValueEntityTestKit` is stateful, and it holds the state of a single entity instance in memory. If you want to test more than one entity in a test, you need to create multiple instance of `KeyValueEntityTestKit`.
+NOTE: The `KeyValueEntityTestKit` is stateful, and it holds the state of a single entity instance in memory. If you want to test more than one entity in a test, you need to create multiple instances of `KeyValueEntityTestKit`.
 
 === Integration tests
 

samples/shopping-cart-quickstart/src/main/java/shoppingcart/application/ShoppingCartEntity.java

@@ -102,10 +102,8 @@ public Effect<Done> checkout() {
   public ShoppingCart applyEvent(ShoppingCartEvent event) {
     return switch (event) {
       case ShoppingCartEvent.ItemAdded evt -> currentState().addItem(evt.item()); // <5>
-      // end::addItem[]
       case ShoppingCartEvent.ItemRemoved evt -> currentState().removeItem(evt.productId());
       case ShoppingCartEvent.CheckedOut evt -> currentState().onCheckedOut();
-      // tag::addItem[]
     };
   }
   // end::addItem[]

samples/shopping-cart-quickstart/src/test/java/shoppingcart/ShoppingCartIntegrationTest.java

@@ -12,7 +12,7 @@ public class ShoppingCartIntegrationTest extends TestKitSupport { // <1>
 
   @Test
   public void createAndManageCart() {
-    String cartId = "card-abc";
+    String cartId = "cart-abc";
     var item1 = new LineItem("tv", "Super TV 55'", 1);
     var response1 = componentClient // <2>
       .forEventSourcedEntity(cartId) // <3>