Focus on value proposition

Author: ejsmith

README.md

@@ -34,9 +34,9 @@ Define a message and a handler — no interfaces or base classes required:
 ```csharp
 public record Ping(string Text);
 
-public static class PingHandler
+public class PingHandler
 {
-    public static string Handle(Ping msg) => $"Pong: {msg.Text}";
+    public string Handle(Ping msg) => $"Pong: {msg.Text}";
 }
 ```
 

docs/guide/getting-started.md

@@ -1,6 +1,8 @@
 # Getting Started
 
-Build a completely message-oriented, loosely coupled app that's easy to test — with near-direct-call performance and zero boilerplate. Get up and running in under a minute.
+Most .NET apps start simple and gradually become a tangled web of services calling services. Foundatio Mediator helps you avoid that from day one. Instead of components calling each other directly, every interaction flows through messages — so your code stays loosely coupled, easy to test, and easy to understand as it grows.
+
+You get all of this with near-direct-call performance and zero boilerplate. Get up and running in under a minute.
 
 ## Quick Start
 
@@ -17,9 +19,9 @@ dotnet add package Foundatio.Mediator
 public record Ping(string Text);
 
 // Any class ending in "Handler" is discovered automatically
-public static class PingHandler
+public class PingHandler
 {
-    public static string Handle(Ping msg) => $"Pong: {msg.Text}";
+    public string Handle(Ping msg) => $"Pong: {msg.Text}";
 }
 ```
 
@@ -209,13 +211,16 @@ See [Clean Architecture](./clean-architecture) for a complete modular monolith e
 | Topic | Description |
 | ----- | ----------- |
 | [Handler Conventions](./handler-conventions) | All discovery rules, method names, static handlers, explicit attributes |
+| [Events & Notifications](./events-and-notifications) | Publish/subscribe, cascading messages, dynamic subscriptions |
+| [Authorization](./authorization) | Built-in auth for endpoints and direct mediator calls, policies, roles |
 | [Dependency Injection](./dependency-injection) | Lifetimes, parameter injection, constructor vs method injection |
 | [Result Types](./result-types) | `Result<T>` API, status codes, validation errors |
 | [Middleware](./middleware) | Pipeline hooks, ordering, state passing, short-circuiting |
 | [Endpoints](./endpoints) | Route conventions, OpenAPI, authorization, filters |
 | [Configuration](./configuration) | All compile-time and runtime options |
 | [Streaming Handlers](./streaming-handlers) | `IAsyncEnumerable<T>` support and dynamic subscriptions |
 | [Performance](./performance) | Benchmarks and how interceptors work |
+| [Clean Architecture](./clean-architecture) | Modular monolith example with cross-assembly handlers |
 | [Troubleshooting](./troubleshooting) | Common issues and solutions |
 
 ::: info LLM-Friendly Docs

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

@@ -1,10 +1,22 @@
 # What is Foundatio Mediator?
 
-Foundatio Mediator is a high-performance, convention-based mediator pattern implementation for .NET applications. It leverages modern C# features like source generators and interceptors to deliver near-direct call performance while maintaining the benefits of the mediator pattern.
+Foundatio Mediator is a convention-based mediator library for .NET that makes it easy to build loosely coupled, maintainable, and testable applications — without sacrificing performance or drowning in boilerplate. It leverages source generators and C# interceptors to deliver near-direct call performance at runtime while giving your team clean architectural boundaries at design time.
 
-## What is the Mediator Pattern?
+## The Problem: How Codebases Become Unmaintainable
 
-The mediator pattern defines how a set of objects interact with each other. Instead of objects communicating directly, they communicate through a central mediator. This promotes loose coupling and makes your code more maintainable and testable.
+Every application starts clean. A controller calls a service, the service calls a repository, and everything is easy to follow. But as the application grows, things get tangled:
+
+- **Services call other services**, creating a web of direct dependencies that's hard to trace and harder to change
+- **Business logic spreads** across controllers, services, and helpers with no clear boundaries
+- **Testing becomes painful** — to test one class, you need to mock a chain of dependencies it was never designed to work without
+- **Changes ripple unpredictably** — a small modification in one service breaks three others that depend on it directly
+- **New team members struggle** to understand what calls what and where a feature actually lives
+
+This is the **big ball of mud** — and it's the natural outcome when components communicate directly instead of through clear, well-defined boundaries.
+
+## The Mediator Pattern: A Way Out
+
+The mediator pattern solves this by introducing a simple rule: **components never call each other directly**. Instead, they send messages through a central mediator, and handlers pick them up on the other side.
 
 ```mermaid
 graph TD
@@ -17,6 +29,16 @@ graph TD
     M --> MW[Middleware]
 ```
 
+This single change has profound effects:
+
+- **Loose coupling** — The sender doesn't know (or care) who handles the message. You can change, replace, or remove handlers without touching callers.
+- **Compose with events** — Publish an event like `OrderCreated` and any number of handlers react — sending emails, updating inventory, writing audit logs — without knowing about each other. Add new behavior without modifying existing code.
+- **Clear boundaries** — Each handler does one thing. Business logic has an obvious home.
+- **Easy testing** — Handlers are self-contained. Test them in isolation with real assertions, not mock verification chains.
+- **Safe refactoring** — Rename, split, or reorganize handlers without breaking the rest of the app.
+
+The catch? Traditional mediator libraries make you pay for these benefits with boilerplate interfaces, runtime reflection overhead, and framework lock-in. Foundatio Mediator eliminates those costs.
+
 ## Key Benefits
 
 ### 🚀 Exceptional Performance
@@ -134,16 +156,28 @@ public class LoggingMiddleware
 }
 ```
 
+## What This Means for Your Team
+
+The features above aren't just technical checkboxes — they translate directly into a healthier codebase and a more productive team:
+
+- **Avoid the big ball of mud** — Message-based communication enforces boundaries that prevent the tight coupling that makes large codebases unmaintainable. Your code stays organized as it grows.
+- **Compose logic through events** — When an order is created, the email handler, audit handler, and inventory handler all react independently. None of them know about each other. Need a new reaction? Add a handler — no existing code changes.
+- **Ship changes confidently** — When handlers are self-contained and loosely coupled, you can modify one feature without worrying about breaking others. Refactoring goes from scary to routine.
+- **Test without fighting the framework** — Handlers are plain classes. Write focused unit tests that assert on real behavior, not mock setups. No mediator fakes, no DI container in tests.
+- **Onboard developers faster** — Clear conventions mean new team members learn the pattern once and can navigate the entire codebase. Every feature follows the same structure: message in, handler processes, result out.
+- **No performance penalty for good architecture** — Unlike other mediator libraries that add measurable overhead per call, Foundatio Mediator compiles away the indirection. You get a well-structured codebase that runs as fast as hand-wired code.
+- **No boilerplate tax** — No marker interfaces, no base classes, no manual DI registration. The source generator handles the wiring so you can focus on business logic.
+
 ## When to Use Foundatio Mediator
 
 ### ✅ Great For
 
+- **Any app that needs to stay maintainable** as it grows beyond a handful of services
 - **Clean Architecture** applications with command/query separation
 - **Microservices** with clear request/response boundaries
 - **Event-driven** architectures with publish/subscribe patterns
-- **High-performance** scenarios where every nanosecond matters
 - **Large teams** needing consistent patterns and conventions
-- **Testing** scenarios requiring isolated, mockable handlers
+- **High-performance** scenarios where mediator overhead is usually accepted as a cost of good architecture
 
 ### ⚠️ Consider Alternatives For
 

docs/guide/why-foundatio-mediator.md

@@ -1,6 +1,26 @@
 # Why Choose Foundatio Mediator?
 
-Foundatio Mediator stands out from other mediator implementations by combining exceptional performance with developer-friendly conventions. Here's why it might be the right choice for your project.
+## The Problem: Complexity That Creeps In
+
+Every .NET application starts clean. But as features accumulate, services start calling other services, dependencies multiply, and before long you have a tightly-coupled codebase that’s hard to test, hard to change, and hard for new team members to navigate. This is the **big ball of mud**, and it’s the default outcome when there’s nothing enforcing boundaries between components.
+
+The mediator pattern solves this: route all interactions through messages instead of direct calls, and your components stay decoupled by design. Need something to happen when an order is created? Publish an `OrderCreated` event — email, audit, and inventory handlers each react independently, without knowing about each other. Adding new behavior means adding a handler, not modifying existing code.
+
+But traditional mediator libraries make you pay for this architecture with boilerplate interfaces, runtime reflection overhead, and framework lock-in.
+
+**Foundatio Mediator gives you the architecture benefits without the costs.**
+
+## What You Actually Get
+
+| Benefit | How |
+| ------- | --- |
+| **Loose coupling without ceremony** | No interfaces, no base classes — just naming conventions. Components communicate through messages, never directly. |
+| **Compose logic through events** | Publish an event and any number of handlers react independently. Add new behavior without touching existing code — the ultimate open/closed principle. |
+| **Testability by default** | Handlers are plain classes. Unit test them like any other object — no mediator mocking, no DI container setup. |
+| **Maintainability at scale** | Clear command/query/event boundaries prevent your codebase from growing into an unmaintainable mess. Every feature follows the same pattern. |
+| **No performance penalty** | Source generators and C# interceptors compile mediator calls into near-direct method calls. The pattern pays for itself. |
+| **No boilerplate tax** | The source generator handles all DI registration, dispatch wiring, and endpoint generation. You write business logic, nothing else. |
+| **Faster onboarding** | New developers learn the conventions once and can navigate the entire codebase. Message in, handler processes, result out. |
 
 ## Performance That Matters
 
@@ -287,11 +307,11 @@ Compare this to complex reflection-based call stacks in other libraries.
 
 ### ✅ Ideal For
 
-- **High-performance applications** where every nanosecond matters
+- **Any app that needs to stay maintainable** as it grows — the mediator pattern prevents the big ball of mud
 - **Clean architecture** implementations with CQRS patterns
 - **Event-driven systems** with publish/subscribe needs
-- **Teams preferring conventions** over explicit interfaces
-- **Applications requiring robust error handling** without exceptions
+- **Teams that value consistency** — conventions mean everyone follows the same patterns
+- **High-performance applications** where other mediator libraries add unacceptable overhead
 - **Projects wanting excellent testing experience** without framework coupling
 
 ### ⚠️ Consider Alternatives When
@@ -336,4 +356,4 @@ Ready to experience the benefits of Foundatio Mediator?
 1. [Installation & Setup](./getting-started) - Get running in minutes
 2. [Simple Examples](https://github.com/FoundatioFx/Foundatio.Mediator/tree/main/samples) - See the patterns in action
 
-The combination of exceptional performance, developer-friendly conventions, and robust error handling makes Foundatio Mediator an excellent choice for modern .NET applications.
+The combination of loose coupling, testability, maintainability, and exceptional performance — without the usual boilerplate tax — makes Foundatio Mediator an excellent choice for modern .NET applications.

docs/index.md

@@ -3,8 +3,8 @@ layout: home
 
 hero:
   name: Foundatio Mediator
-  text: Blazingly Fast C# Mediator
-  tagline: Convention-based mediator powered by source generators and interceptors
+  text: Build Loosely Coupled .NET Apps — Without the Tradeoffs
+  tagline: Easy to maintain, easy to test, and blazingly fast — a convention-based mediator powered by source generators and interceptors
   image:
     src: https://raw.githubusercontent.com/FoundatioFx/Foundatio/main/media/foundatio-icon.png
     alt: Foundatio Mediator
@@ -17,21 +17,29 @@ hero:
       link: https://github.com/FoundatioFx/Foundatio.Mediator
 
 features:
+  - icon: 🧩
+    title: Loosely Coupled by Default
+    details: Every interaction flows through messages, so components never call each other directly. Change, replace, or remove any handler without ripple effects across your codebase.
+    link: /guide/what-is-foundatio-mediator
+  - icon: 🔗
+    title: Compose with Events
+    details: Publish an event and any number of handlers react — without knowing about each other. Add new behavior to your app without modifying existing code.
+    link: /guide/events-and-notifications
+  - icon: 🧪
+    title: Easy to Test
+    details: Handlers are plain classes with no framework base types. Unit test them like any other object — no mediator mocking, no DI container, no ceremony.
+    link: /guide/testing
   - icon: ⚡
-    title: Near-Direct Call Performance
-    details: Zero runtime reflection with source generators and C# interceptors for blazing fast execution.
+    title: No Performance Tax
+    details: Source generators and C# interceptors compile your mediator calls into near-direct method calls. You get the architecture benefits without the runtime overhead.
     link: /guide/performance
   - icon: 🎯
-    title: Convention-Based Discovery
-    details: No interfaces or base classes required. Just name your classes and methods following simple conventions.
-    link: /guide/handler-conventions
-  - icon: 🧩
-    title: Plain Handler Classes
-    details: Use regular classes or static methods. Sync or async, any signature, multiple handlers per class. No framework coupling.
+    title: Convention-Based, Zero Boilerplate
+    details: No interfaces, no base classes, no manual registration. Just name your classes and methods following simple conventions — the source generator handles all the wiring.
     link: /guide/handler-conventions
   - icon: 🌐
     title: Auto-Generated API Endpoints
-    details: Full Minimal API endpoints generated from your handlers — routes, methods, parameter binding, OpenAPI metadata, and authorization all inferred automatically. No boilerplate.
+    details: Full Minimal API endpoints generated from your handlers — routes, methods, parameter binding, OpenAPI metadata, and authorization all inferred automatically.
     link: /guide/endpoints
   - icon: 📡
     title: Real-Time Streaming
@@ -54,15 +62,8 @@ features:
     details: Return tuples to automatically publish additional messages in sequence — ideal for event-driven workflows.
     link: /guide/cascading-messages
   - icon: 🔒
-    title: Compile-Time Safety
-    details: Comprehensive compile-time diagnostics and validation to catch errors early.
-    link: /guide/troubleshooting
-  - icon: 🧪
-    title: Easy Testing
-    details: Handlers are plain objects, making unit testing straightforward without framework mocking.
-  - icon: 🐛
-    title: Superior Debugging
-    details: Short, simple call stacks with minimal indirection for excellent debugging experience.
+    title: Compile-Time Safety & Debugging
+    details: Comprehensive diagnostics catch errors early. Short, simple call stacks with minimal indirection make debugging straightforward.
 ---
 
 ## Quick Example
@@ -72,9 +73,9 @@ Create a simple handler by following naming conventions:
 ```csharp
 public record Ping(string Text);
 
-public static class PingHandler
+public class PingHandler
 {
-    public static string Handle(Ping msg) => $"Pong: {msg.Text}";
+    public string Handle(Ping msg) => $"Pong: {msg.Text}";
 }
 ```