Remove some sections

Author: ejsmith

README.md

@@ -141,7 +141,7 @@ public async Task<(User user, UserCreated evt)> HandleAsync(CreateUser cmd)
 
 // Usage
 var user = await mediator.InvokeAsync<User>(new CreateUser(...));
-// UserCreated is auto-published
+// UserCreated is auto-published and handlers invoked inline before this method returns
 ```
 
 ## 📦 Publish API & Behavior
@@ -152,142 +152,6 @@ await mediator.PublishAsync(new OrderShipped(orderId));
 
 All handlers run in parallel; if any fail, PublishAsync throws.
 
-### Example: Complete CRUD with Result Types
-
-```csharp
-public record GetUserQuery(int Id);
-public record UpdateUserCommand(int Id, string Name, string Email);
-public record DeleteUserCommand(int Id);
-
-public class UserHandler
-{
-    public async Task<Result<User>> HandleAsync(GetUserQuery query)
-    {
-        var user = await _repository.GetByIdAsync(query.Id);
-        return user != null
-            ? Result.Ok(user)
-            : Result.NotFound($"User with ID {query.Id} not found");
-    }
-
-    public async Task<Result<User>> HandleAsync(UpdateUserCommand command)
-    {
-        var existingUser = await _repository.GetByIdAsync(command.Id);
-        if (existingUser == null)
-            return Result.NotFound($"User with ID {command.Id} not found");
-
-        if (await _repository.EmailExistsAsync(command.Email, command.Id))
-            return Result.Conflict("Another user already has this email address");
-
-        var updatedUser = existingUser with { Name = command.Name, Email = command.Email };
-        await _repository.UpdateAsync(updatedUser);
-
-        return Result.Ok(updatedUser);
-    }
-
-    public async Task<Result> HandleAsync(DeleteUserCommand command)
-    {
-        var deleted = await _repository.DeleteAsync(command.Id);
-        return deleted
-            ? Result.NoContent()
-            : Result.NotFound($"User with ID {command.Id} not found");
-    }
-}
-```
-
-## 🔄 Cascading Messages - Elegant Event Choreography
-
-Foundatio.Mediator supports **cascading messages** through tuple return types, enabling elegant event choreography where handlers can trigger additional messages automatically. This is perfect for implementing event-driven workflows and the saga pattern.
-
-### How Cascading Messages Work
-
-When a handler returns a tuple, the mediator automatically:
-
-1. **Returns the expected type** to the caller (if specified)
-2. **Publishes remaining tuple items** as cascading events using `PublishAsync`
-3. **Waits for completion** - all cascading messages are processed before the original call completes
-
-### Example: Order Processing with Cascading Events
-
-```csharp
-// Messages
-public record CreateOrder(string ProductName, decimal Amount, string CustomerEmail);
-public record Order(int Id, string ProductName, decimal Amount, string CustomerEmail, DateTime CreatedAt);
-public record OrderCreatedEvent(int OrderId, string CustomerEmail, decimal Amount);
-public record SendWelcomeEmail(string Email, string CustomerName);
-public record UpdateInventory(string ProductName, int Quantity);
-
-// Handler that returns a tuple - triggers cascading messages
-public class CreateOrderHandler
-{
-    public async Task<(Order, OrderCreatedEvent)> HandleAsync(CreateOrder command, CancellationToken cancellationToken)
-    {
-        // Create the order
-        var order = new Order(
-            Id: Random.Shared.Next(1000, 9999),
-            ProductName: command.ProductName,
-            Amount: command.Amount,
-            CustomerEmail: command.CustomerEmail,
-            CreatedAt: DateTime.UtcNow
-        );
-
-        // Create the event that will be published automatically
-        var orderCreatedEvent = new OrderCreatedEvent(order.Id, order.CustomerEmail, order.Amount);
-
-        // Return tuple - Order goes to caller, OrderCreatedEvent gets published
-        return (order, orderCreatedEvent);
-    }
-}
-
-// Handler for the cascading event
-public class OrderCreatedEventHandler
-{
-    public async Task HandleAsync(OrderCreatedEvent orderCreated, CancellationToken cancellationToken)
-    {
-        Console.WriteLine($"Order {orderCreated.OrderId} created for ${orderCreated.Amount}");
-
-        // Could trigger more cascading messages by returning a tuple
-        // For example: return (new SendWelcomeEmail(orderCreated.CustomerEmail, "Valued Customer"),);
-    }
-}
-```
-
-### Usage with Cascading Messages
-
-```csharp
-// Only the Order is returned to the caller
-// OrderCreatedEvent is automatically published to all its handlers
-var order = await mediator.InvokeAsync<Order>(new CreateOrder(
-    ProductName: "Amazing Widget",
-    Amount: 29.99m,
-    CustomerEmail: "customer@example.com"
-));
-
-Console.WriteLine($"Created order {order.Id} - cascading events processed automatically!");
-```
-
-### Multiple Cascading Messages
-
-Handlers can return tuples with multiple cascading messages:
-
-```csharp
-public class ComplexOrderHandler
-{
-    public async Task<(Order, OrderCreatedEvent, SendWelcomeEmail, UpdateInventory)> HandleAsync(
-        CreateOrder command,
-        CancellationToken cancellationToken)
-    {
-        var order = new Order(/*...*/);
-
-        return (
-            order,                                           // Returned to caller
-            new OrderCreatedEvent(order.Id, order.CustomerEmail, order.Amount),  // Published
-            new SendWelcomeEmail(order.CustomerEmail, "Valued Customer"),        // Published
-            new UpdateInventory(order.ProductName, -1)                          // Published
-        );
-    }
-}
-```
-
 ## 📊 Performance Benchmarks
 
 Foundatio.Mediator delivers exceptional performance, getting remarkably close to direct method calls while providing full mediator pattern benefits: