Doc updates

Author: ejsmith

README.md

@@ -20,6 +20,40 @@ Blazingly fast, convention-based C# mediator powered by source generators and in
 - 🧪 **Easy testing** - Plain objects, no framework coupling
 - 🐛 **Superior debugging** - Short, simple call stacks
 
+### Why Convention-Based?
+
+Traditional mediator libraries force you into rigid interface contracts like `IRequestHandler<TRequest, TResponse>`. This means:
+
+- One handler class per message type
+- Fixed method signatures
+- Always async (even for simple operations)
+- Lots of boilerplate
+
+**Foundatio Mediator's conventions give you freedom:**
+
+```csharp
+public class OrderHandler
+{
+    // Sync handler - no async overhead
+    public decimal Handle(CalculateTotal query) => query.Items.Sum(i => i.Price);
+
+    // Async with any DI parameters you need
+    public async Task<Order> HandleAsync(GetOrder query, IOrderRepo repo, CancellationToken ct)
+        => await repo.FindAsync(query.Id, ct);
+
+    // Cascading: first element returned, rest auto-published as events
+    public (Order order, OrderCreated evt) Handle(CreateOrder cmd) { /* ... */ }
+}
+
+// Static handlers for maximum performance
+public static class MathHandler
+{
+    public static int Handle(Add query) => query.A + query.B;
+}
+```
+
+> **Prefer explicit interfaces?** Use `IHandler` marker interface or `[Handler]` attributes instead. See [Handler Conventions](https://mediator.foundatio.dev/guide/handler-conventions.html#explicit-handler-declaration).
+
 ## 🚀 Complete Example
 
 ### 1. Install & Register

docs/guide/handler-conventions.md

@@ -2,6 +2,30 @@
 
 Foundatio Mediator uses simple naming conventions to automatically discover handlers at compile time. This eliminates the need for interfaces, base classes, or manual registration while providing excellent compile-time validation.
 
+## Why Conventions?
+
+Some developers initially feel that convention-based discovery is "too magical." But consider: **all abstractions are magic until you learn them.**
+
+- ASP.NET discovers `*Controller` classes automatically
+- Entity Framework treats `Id` properties as primary keys
+- xUnit runs methods decorated with `[Fact]`
+- C# records generate equality, `ToString()`, and more from a single line
+
+The real question isn't "is it magic?" but **"does the magic help or hurt?"**
+
+Convention-based handlers provide tangible benefits over traditional interface-based approaches:
+
+| Benefit | Convention-Based | Interface-Based |
+| ------- | ---------------- | --------------- |
+| **Multiple handlers per class** | ✅ Natural grouping | ❌ One interface per handler |
+| **Flexible method signatures** | ✅ Any params via DI | ❌ Fixed `Handle(TRequest, CancellationToken)` |
+| **Sync or async** | ✅ Return `void`, `T`, `Task<T>`, etc. | ❌ Must return `Task<T>` |
+| **Static handlers** | ✅ Zero allocation | ❌ Always instance-based |
+| **Cascading messages** | ✅ Tuple returns auto-publish | ❌ Manual `IPublisher` injection |
+| **Boilerplate** | ✅ Just a class + methods | ❌ Interface inheritance per handler |
+
+**Prefer explicit declaration?** Use `IHandler` or `[Handler]` attributes. See [Explicit Handler Declaration](#explicit-handler-declaration).
+
 Alternatively, you can mark handlers explicitly using the `IHandler` marker interface or the `[Handler]` attribute. See [Explicit Handler Declaration](#explicit-handler-declaration) for details.
 
 ## Class Naming Conventions

docs/guide/what-is-foundatio-mediator.md

@@ -52,6 +52,22 @@ public static class OrderHandler
 }
 ```
 
+Unlike traditional mediator libraries that lock you into rigid interface contracts, conventions give you **unprecedented flexibility**:
+
+- **Sync or async** - Return `void`, `Task`, `T`, `Task<T>`, `ValueTask<T>`
+- **Any parameters** - Message first, then any dependencies injected automatically
+- **Multiple handlers per class** - Group related operations naturally
+- **Static handlers** - Zero allocation for stateless operations
+- **Tuple returns** - Cascading messages for event-driven workflows
+
+```csharp
+// All of these are valid handlers:
+public int Handle(AddNumbers q) => q.A + q.B;                    // Sync, returns value
+public void Handle(LogMessage cmd) => _log.Info(cmd.Text);       // Fire-and-forget
+public async Task<User> HandleAsync(GetUser q, IRepo r) => ...;  // Async with DI
+public (Order, OrderCreated) Handle(CreateOrder c) => ...;       // Cascading events
+```
+
 ### 🔧 Seamless Dependency Injection
 
 Full support for Microsoft.Extensions.DependencyInjection with both constructor and method injection:
@@ -134,7 +150,8 @@ public class LoggingMiddleware
 - **Simple CRUD** applications with minimal business logic
 - **Performance-critical** inner loops where even 10ns matters
 - **Legacy codebases** that can't adopt modern .NET features
-- **Teams resistant** to convention-based approaches
+
+> **Note:** If you prefer explicit interfaces over conventions, Foundatio Mediator fully supports that too! Use `IHandler` marker interface or `[Handler]` attributes, and optionally disable conventional discovery. See [Handler Conventions](./handler-conventions#explicit-handler-declaration) for details.
 
 ## Next Steps
 

docs/guide/why-foundatio-mediator.md

@@ -45,6 +45,83 @@ public class UserHandler : IRequestHandler<GetUser, User>
 }
 ```
 
+### But Isn't Convention-Based Discovery "Too Magic"?
+
+Some developers prefer explicit interfaces because they feel conventions are "too magical." Let's address this concern directly.
+
+**All abstractions are "magic."** Consider what you already accept without question:
+
+- **ASP.NET Controllers** - Classes ending in `Controller` are automatically discovered and routed
+- **Entity Framework** - Properties named `Id` become primary keys; navigation properties create relationships
+- **xUnit/NUnit** - Methods with `[Fact]` or `[Test]` attributes are discovered and executed
+- **Dependency Injection** - Constructor parameters are magically resolved from a container
+- **C# Records** - `record Person(string Name)` generates equality, `ToString()`, and deconstruction
+
+The difference between "magic" and "convention" is simply **familiarity**. Once you learn a convention, it becomes invisible—you stop thinking about it.
+
+**Why conventions are actually _better_ for mediator patterns:**
+
+| Traditional Interfaces | Convention-Based |
+| ---------------------- | ---------------- |
+| Forces `IRequestHandler<TRequest, TResponse>` inheritance | Plain classes with any name ending in `Handler` |
+| One handler method per class (or awkward multiple interface inheritance) | Multiple handler methods per class, naturally grouped |
+| Fixed method signature: `Handle(TRequest, CancellationToken)` | Flexible signatures: sync/async, any parameters via DI |
+| Must return `Task<TResponse>` even for sync operations | Return `void`, `Task`, `T`, `Task<T>`, `Result<T>`, tuples |
+| Handler classes must be registered in DI | Auto-discovered at compile time |
+| Runtime dispatch via reflection | Compile-time interceptors for near-direct call performance |
+
+**With conventions, you get unprecedented flexibility:**
+
+```csharp
+// Sync handler - no async overhead
+public int Handle(AddNumbers query) => query.A + query.B;
+
+// Async handler with injected dependencies
+public async Task<User> HandleAsync(GetUser query, IUserRepo repo, CancellationToken ct)
+    => await repo.FindAsync(query.Id, ct);
+
+// Static handler - zero allocation, maximum performance
+public static class MathHandler
+{
+    public static int Handle(Multiply query) => query.A * query.B;
+}
+
+// Multiple handlers in one cohesive class
+public class OrderHandler
+{
+    public Result<Order> Handle(CreateOrder cmd) { /* ... */ }
+    public Result<Order> Handle(GetOrder query) { /* ... */ }
+    public Result Handle(DeleteOrder cmd) { /* ... */ }
+}
+
+// Cascading messages with tuple returns
+public (User user, UserCreated evt) Handle(CreateUser cmd)
+{
+    var user = CreateUser(cmd);
+    return (user, new UserCreated(user.Id)); // Event auto-published!
+}
+```
+
+**If you still prefer explicit declaration**, that's supported too:
+
+```csharp
+// Use IHandler marker interface
+public class MyService : IHandler
+{
+    public User Handle(GetUser query) { /* ... */ }
+}
+
+// Or use [Handler] attribute on class or method
+[Handler]
+public class AnotherService
+{
+    public void Process(SendEmail cmd) { /* ... */ }
+}
+
+// Disable conventions entirely via MSBuild
+// <MediatorDisableConventionalDiscovery>true</MediatorDisableConventionalDiscovery>
+```
+
 ### Rich Error Handling
 
 Built-in `Result<T>` types eliminate exception-driven control flow:
@@ -221,9 +298,10 @@ Compare this to complex reflection-based call stacks in other libraries.
 
 - **Legacy .NET Framework** projects (requires modern .NET)
 - **Simple CRUD applications** without complex business logic
-- **Teams preferring explicit interfaces** over conventions
 - **Existing MediatR codebases** where migration cost isn't justified
 
+> **Note:** If your team prefers explicit interfaces over conventions, Foundatio Mediator supports that too! Use `IHandler` or `[Handler]` attributes and optionally disable conventional discovery entirely. See [Explicit Handler Declaration](./handler-conventions#explicit-handler-declaration).
+
 ## Migration from Other Libraries
 
 ### From MediatR