com.wallstop-studios.dxmessaging 2.0.0-rc27.3 → 2.0.0

package/Docs/Comparisons.md

@@ -1,75 +1,127 @@
-# Comparisons: Events, Unity Events, and Unity Messages
+# Comparisons: DxMessaging vs. Everything Else
 
-This guide shows common pain points in standard approaches and how DxMessaging addresses them with clearer ownership, ordering, and observability.
+**TL;DR:** If you've used C# events, UnityEvents, or static event buses and thought "there has to be a better way," you're right. DxMessaging fixes the pain points while keeping the benefits.
 
-Table of contents
+## This guide shows
 
-- C# events/delegates
-- UnityEvents (inspector wiring)
-- Unity SendMessage
-- Global “Event Bus” singletons
-- How DxMessaging addresses each
-- When to use which
+- What's wrong with each approach (with real code examples)
+- How DxMessaging solves it (with real code examples)
+- Honest trade-offs (what you give up, what you gain)
+- When to actually use each approach (no BS)
 
-Standard C# Events/Actions
+### Table of Contents
 
-Problems
+- [C# Events/Delegates](#standard-c-eventsactions)
+- [UnityEvents](#unityevents-inspector-wiring)
+- [Unity SendMessage](#unity-sendmessage)
+- [Static Event Buses](#global-event-bus-singletons)
+- [Honest Trade-offs](#honest-trade-offs-what-you-give-up-what-you-gain)
+- [Feature Matrix](#feature-by-feature-comparison-matrix)
+- [Decision Guide](#when-each-approach-actually-wins)
 
-- Manual attach/detach: easy to forget unsubscribe; memory leaks and callbacks on destroyed objects.
-- Tight coupling: consumers reference producers (or vice‑versa), hurting modularity and tests.
-- Ordering is implicit: hard to coordinate A before B across systems.
-- Hard to observe globally: no built‑in way to inspect “what fired recently”.
+## Standard C# Events/Actions
 
-Typical code
+### The Pain Points (You've Felt These)
+
+#### 1. Memory Leak Hell
 
 ```csharp
-public sealed class Spawner
-{
-    public event Action Spawned;
-    public void Spawn()
-    {
-        // ...
-        Spawned?.Invoke();
+public class UI : MonoBehaviour {
+    void OnEnable() {
+        GameManager.Instance.OnScoreChanged += UpdateScore;
+    }
+
+    void OnDisable() {
+        // ❌ Forgot this line? MEMORY LEAK!
+        GameManager.Instance.OnScoreChanged -= UpdateScore;
     }
 }
+```
 
-public sealed class UI
-{
-    private readonly Spawner _spawner;
-    public UI(Spawner spawner)
-    {
-        _spawner = spawner;
-        _spawner.Spawned += OnSpawned; // must remember to unsubscribe
+**Real story:** You forget `OnDisable` once. Six months later: "Why is our mobile game crashing after 30 minutes?"
+
+##### 2. Tight Coupling Nightmare
+
+```csharp
+public class Spawner {
+    public event Action Spawned;
+    public void Spawn() => Spawned?.Invoke();
+}
+
+public class UI {
+    // ❌ UI now depends on Spawner directly
+    [SerializeField] private Spawner spawner;
+
+    void Awake() {
+        spawner.Spawned += OnSpawned;  // Tight coupling
     }
-    private void OnSpawned() => Refresh();
 }
 ```
 
-DxMessaging
+**Problem:** Want to add a second spawner? Refactor Spawner? Hope you like breaking things.
 
-- No direct coupling; the UI listens for a message instead of referencing a specific Spawner instance.
-- Lifecycle managed by a token; enable/disable tied to a component.
-- Ordering via priority; global inspection via diagnostics and the custom inspector.
+###### 3. Mystery Execution Order
 
 ```csharp
-using DxMessaging.Core.Attributes;
-using DxMessaging.Core.Extensions;
-using DxMessaging.Core.Messages;
+// Which runs first? 🤷
+AudioSystem.OnGameEnd += FadeMusic;
+SaveSystem.OnGameEnd += SaveGame;
+UISystem.OnGameEnd += ShowCredits;
+```
 
-[DxUntargetedMessage]
-[DxAutoConstructor]
-public readonly partial struct Spawned { }
+**Result:** Sometimes SaveGame runs after UISystem shows credits. Flaky bugs that only happen sometimes.
 
-// Producer
-var evt = new Spawned();
-evt.Emit();
+###### 4. Debugging Black Hole
+
+"Which event fired when? Who's subscribed?" → Set 50 breakpoints and hope.
+
+### The DxMessaging Way
+
+#### 1. Impossible to Leak
+
+```csharp
+public class UI : MessageAwareComponent {
+    protected override void RegisterMessageHandlers() {
+        base.RegisterMessageHandlers();
+        _ = Token.RegisterUntargeted<ScoreChanged>(UpdateScore);
+    }
+    // ✅ That's it! Automatic cleanup when destroyed.
+}
+```
+
+##### 2. Zero Coupling
+
+```csharp
+// Spawner doesn't know about UI
+public class Spawner : MonoBehaviour {
+    void Spawn() {
+        // Just emit, don't care who's listening
+        new SpawnedEnemy().Emit();
+    }
+}
 
-// Consumer (Unity)
-_ = token.RegisterUntargeted<Spawned>(OnSpawned);
-void OnSpawned(ref Spawned m) => Refresh();
+// UI doesn't know about Spawner
+public class UI : MessageAwareComponent {
+    protected override void RegisterMessageHandlers() {
+        _ = Token.RegisterUntargeted<SpawnedEnemy>(OnSpawn);
+    }
+}
 ```
 
-UnityEvents (inspector wiring)
+###### 3. Explicit Execution Order
+
+```csharp
+// Clear, documented order
+AudioSystem:  priority: 10  // Runs third
+SaveSystem:   priority: 0   // Runs first
+UISystem:     priority: 5   // Runs second
+```
+
+###### 4. Built-in Debugging
+
+Open any component in Inspector → See message history with timestamps. Done.
+
+## UnityEvents (Inspector Wiring)
 
 Problems
 
@@ -99,7 +151,7 @@ DxMessaging
 - Strongly‑typed registrations in code; explicit priorities and stages.
 - Inspect and page through emissions/registrations from MessagingComponent inspector.
 
-Unity SendMessage
+## Unity SendMessage
 
 Problems
 
@@ -120,7 +172,7 @@ var msg = new ReflexiveMessage("OnHit", ReflexiveSendMode.Upwards, 10);
 MessageHandler.MessageBus.TargetedBroadcast(ref target, ref msg);
 ```
 
-Global “Event Bus” singletons
+## Global Event Bus Singletons
 
 Problems
 
@@ -183,23 +235,36 @@ When to use which
 
 ## Honest Trade-offs: What You Give Up, What You Gain
 
-No solution is perfect. Here's what you sacrifice and gain with DxMessaging compared to alternatives.
+**Let's be real:** DxMessaging isn't free magic. You trade some things for others. Here's the unfiltered truth about what you gain and what you sacrifice.
+
+**Bottom line first:** For game jam prototypes, C# events are faster to write. For anything you'll maintain for months, DxMessaging saves you time and sanity.
 
 ### Learning Curve
 
 #### What You Give Up
 
-- ❌ Immediate productivity - There's a 1-2 day learning curve
-- ❌ Familiarity - Team needs to understand message types, tokens, and lifecycle
-- ❌ "Just works" - Requires upfront design (which message type? what priority?)
+- ❌ **Immediate productivity** - ~1-2 days to feel comfortable (reading docs, trying examples)
+- ❌ **Familiarity** - Your team knows C# events already; DxMessaging is new
+- ❌ **"Just works" intuition** - You need to think: "Which message type? What priority?"
+
+**Real talk:** Your first message will take 15 minutes. By the 10th message, you'll be faster than with events.
 
 #### What You Gain
 
-- ✅ Long-term velocity - Once learned, adding features is faster
-- ✅ Reduced debugging time - Clear message flow, Inspector diagnostics
-- ✅ Onboarding clarity - New devs see explicit message contracts instead of hidden event chains
+- ✅ **Long-term velocity** - Adding new features doesn't require touching 5 existing systems
+- ✅ **Debugging is 10x faster** - Inspector shows "what fired when" instantly
+- ✅ **Onboarding is easier** - New devs see explicit message contracts, not hidden event chains
+
+**Example:** Junior dev asks "How does damage work?"
+
+- **C# events:** "Uh, Player has an OnDamaged event, and HealthBar subscribes in line 47, and..."
+- **DxMessaging:** "Search for `TookDamage` message, see who emits it and who listens."
 
-**Verdict:** If you're building a game jam prototype, the learning curve isn't worth it. For multi-month projects, it pays off quickly.
+##### Verdict
+
+- Game jam (1 week project): Learning curve not worth it → Stick with C# events
+- Mid-size game (1+ month): Pays off by week 2
+- Large game (6+ months): Essential for sanity
 
 ### Boilerplate
 
@@ -449,17 +514,80 @@ public void TestAchievementSystem() {
 
 **Break-even point:** Usually around 10-20 hours into a project, when event management becomes painful.
 
-## Making the Decision
+## Making the Decision (Be Honest With Yourself)
+
+### Answer these questions honestly
+
+### 1. Project Lifespan?
+
+- **<1 week (game jam):** Skip DxMessaging → Use C# events or direct calls
+- **1-4 weeks (prototype):** Maybe → If you plan to continue, use DxMessaging
+- **1+ months (real project):** Yes → DxMessaging will save you time
+- **6+ months (production):** Absolutely → You'll thank yourself later
+
+### 2. Team Size?
+
+- **Solo dev:** Optional → Depends on project complexity
+- **2-3 devs:** Valuable → Reduces communication overhead
+- **4+ devs:** Highly recommended → Clear contracts between systems
+- **Remote/distributed team:** Essential → Explicit message contracts prevent miscommunication
+
+### 3. Codebase Size?
+
+- **<1k lines:** Skip it → Direct method calls are fine
+- **1k-5k lines:** Consider it → If you're growing fast
+- **5k-20k lines:** Recommended → Coupling becomes painful
+- **20k+ lines:** Absolutely → Refactoring without it is a nightmare
+
+### 4. How Many Systems Need to Communicate?
+
+- **1-2 systems:** Skip → Just call methods directly
+- **3-5 systems:** Consider → If they don't share references
+- **6-10 systems:** Recommended → Coupling becomes unmanageable
+- **10+ systems:** Essential → You're drowning in SerializeFields
+
+### 5. Have You Had Memory Leaks From Forgotten Unsubscribes?
+
+- **Never:** Lucky you! Optional
+- **Once or twice:** Consider it → Prevention is cheaper than debugging
+- **Multiple times:** Absolutely → Stop wasting time on this
+- **Currently debugging one:** Drop everything and adopt DxMessaging now
+
+### 6. How Often Do You Debug "What Fired When?"
+
+- **Never:** You're either lying or working on tiny projects
+- **Rarely:** Optional, but would help
+- **Monthly:** Recommended → Inspector diagnostics will save hours
+- **Weekly:** Absolutely → You're wasting too much time
+
+### Quick Decision Matrix
+
+```text
+Game Jam         → C# Events (speed over safety)
+Prototype        → DxMessaging IF continuing, else C# Events
+Production       → DxMessaging (unless <1k lines)
+Legacy codebase  → Migrate gradually (see Migration Guide)
+```
+
+### The Real Question
+
+#### "Will this project still exist in 3 months?"
+
+- **No:** C# events are fine
+- **Yes:** Use DxMessaging
+
+##### "Will anyone else work on this code?"
+
+- **No:** C# events might be okay
+- **Yes:** Use DxMessaging (future you counts as "someone else")
 
-Ask yourself:
+### Rule of Thumb
 
-1. **Project lifespan?** <1 week → Skip DxMessaging | >1 month → Consider it
-1. **Team size?** Solo → Optional | 3+ devs → Highly valuable
-1. **Codebase size?** <5k lines → Optional | >10k lines → Recommended
-1. **Event complexity?** <10 events → Skip | >20 events → Use DxMessaging
-1. **Memory leak history?** None → Optional | Frequent → MUST HAVE
+If you're reading this and thinking:
 
-**Rule of thumb:** If you're reading this and thinking "I've experienced these pain points," DxMessaging will help. If you're thinking "I've never had these problems," maybe you don't need it yet.
+- **"I've experienced these pain points"** → DxMessaging will help
+- **"This seems like overkill"** → You probably don't need it yet
+- **"I need this yesterday"** → Welcome home 🚀
 
 See also
 

package/Docs/GettingStarted.md

@@ -27,13 +27,31 @@ By the end of this guide, you will:
 
 ## What is DxMessaging?
 
-DxMessaging is a high‑performance, type‑safe messaging system for Unity. It replaces sprawling C# events, brittle UnityEvents, and ad‑hoc global buses with clean, observable, and predictable communication.
+**Picture this:** You're building a Unity game. Your player takes damage. Now you need to:
 
-Think of it as the event system you wish Unity had built‑in:
+- Update the health bar UI
+- Play a damage sound
+- Show a damage number popup
+- Track damage for analytics
+- Check if an achievement unlocked
+- Maybe trigger a tutorial tip
 
-- Decoupled systems without manual subscribe/unsubscribe headaches
-- Predictable execution order with powerful interception and diagnostics
-- Scales from prototypes to large production codebases
+**The old way:** The Player script needs references to all 6 systems. Or they all need references to the Player. It's a tangled mess.
+
+**The DxMessaging way:** The Player emits one message: `TookDamage(25)`. Everyone who cares receives it automatically. Zero coupling, zero leaks, zero hassle.
+
+---
+
+**Technical summary:** DxMessaging is a high-performance, type-safe messaging system that replaces C# events, UnityEvents, and global event buses with a clean, observable, and predictable communication pattern.
+
+**Think of it as:** The event system Unity should have shipped with.
+
+### What you get
+
+- **Decoupled systems** - no manual subscribe/unsubscribe, impossible to leak
+- **Predictable execution** - priority-based ordering, see exactly what runs when
+- **Actually debuggable** - Inspector shows message history with timestamps
+- **Scales effortlessly** - works for prototypes and 100k+ line codebases
 
 ## Quick Start
 
@@ -91,27 +109,76 @@ heal.EmitGameObjectTargeted(playerGameObject);
 
 ## Message Types
 
-- Untargeted: fire‑and‑forget announcements (no specific receiver)
-- Targeted: deliver to a specific receiver (GameObject, InstanceId, etc.)
-- Broadcast: deliver to all listeners (optionally including source metadata)
+### New to messaging? Use this decision tree
+
+```text
+Is it a global announcement? (pause, settings, scene load)
+  → Use UNTARGETED
+
+Are you commanding a specific entity? (heal Player, open Chest #3)
+  → Use TARGETED
+
+Is an entity announcing something happened? (Enemy died, Chest opened)
+  → Use BROADCAST
+```
+
+#### Examples
+
+```csharp
+// Untargeted: "Everyone, the game paused!"
+[DxUntargetedMessage]
+public struct GamePaused { }
+
+// Targeted: "Player, heal yourself by 50!"
+[DxTargetedMessage]
+public struct Heal { public int amount; }
 
-See [MessageTypes](MessageTypes.md) for details and APIs.
+// Broadcast: "I (Enemy #3) just died!"
+[DxBroadcastMessage]
+public struct EnemyDied { public string enemyName; }
+```
+
+**Still confused?** See the [Visual Guide](VisualGuide.md) for beginner-friendly explanations, or [MessageTypes](MessageTypes.md) for technical details.
 
 ## Common Patterns
 
-- UI reacting to gameplay state via targeted messages
-- Cross‑system notifications using broadcast messages
-- Configuration changes/feature toggles via untargeted announcements
+### Want to see real examples? Here's what DxMessaging excels at
+
+- **UI reacting to gameplay** - Health bar updates when player takes damage (without UI knowing about Player)
+- **Achievement systems** - Track ALL kills across ALL enemies with ONE listener
+- **Cross-system coordination** - Scene transitions coordinate audio, save system, and UI automatically
+- **Input handling** - Decouple input system from player controller
+- **Analytics** - Track all events without polluting gameplay code
 
-See [ListeningPatterns](ListeningPatterns.md) and [Patterns](Patterns.md) for deeper examples.
+**Want code examples?** See [Patterns](Patterns.md) for production-ready patterns and [ListeningPatterns](ListeningPatterns.md) for advanced techniques.
 
 ## Troubleshooting
 
-- Nothing happens? Ensure your listener registered in `RegisterMessageHandlers` and the component is enabled.
-- Duplicate behavior? Check for multiple registrations or missing token disposal on custom lifecycles.
-- Ordering issues? Use interceptors/post‑processors to control/inspect flow.
+### "My handler isn't being called!"
+
+✅ Checklist:
+
+1. Did you call `base.RegisterMessageHandlers()` first?
+1. Is your component enabled in the scene?
+1. Are you emitting to the right target? (Check GameObject vs Component)
+1. Check the Inspector - does the registration show up?
+
+#### "My message is firing twice!"
+
+- Check if you accidentally registered the same handler multiple times
+- Make sure you're calling `base.RegisterMessageHandlers()` only once
+
+##### "I get a compile error on `[DxAutoConstructor]`"
+
+- Did you mark the struct as `partial`? (required for code generation)
+- Example: `public readonly partial struct MyMessage`
+
+###### "Which message type should I use?"
+
+- See the decision tree in [Message Types](#message-types) above
+- When in doubt, start with `Broadcast` - it's the most flexible
 
-See [Troubleshooting](Troubleshooting.md) for more.
+**Still stuck?** See [Troubleshooting](Troubleshooting.md) for the complete guide or [FAQ](FAQ.md) for common questions.
 
 ## Next Steps
 

package/Docs/Overview.md

@@ -4,22 +4,89 @@
 
 ---
 
-DxMessaging is a high‑performance, type‑safe messaging system for Unity and .NET that decouples producers and consumers without sprawling events or brittle global hooks. It gives you clear message categories, predictable ordering, and tooling to observe, intercept, and diagnose message flows.
+DxMessaging is a high-performance, type-safe messaging system for Unity that **eliminates the three biggest pain points** of traditional event systems:
 
-What it solves
+1. **Memory leaks** from forgotten unsubscribes → Automatic lifecycle management
+1. **Tight coupling** creating refactoring nightmares → Full decoupling with no direct references
+1. **Debugging black holes** ("what fired when?") → Built-in Inspector diagnostics
 
-- Decoupling without tight references: producers don’t need to know consumers.
-- Predictable lifecycle: explicit registration tokens that you enable/disable with Unity components.
-- Ergonomics and performance: struct‑friendly APIs, by‑ref handlers, zero‑boxing patterns.
-- Observability: interceptors, post‑processors, diagnostics buffers, and registration logs.
-- Scalable message taxonomy: Untargeted, Targeted, and Broadcast messages fit most gameplay/UI flows.
+## What Problems Does It Solve?
 
-When to consider DxMessaging
+### For Beginners: "I'm calling methods manually everywhere"
 
-- You’re fighting complex webs of C# events/delegates with manual attach/detach and order issues.
-- You need to decouple systems that span scenes or don’t share direct references.
-- You want to model Gameplay/UI flows as messages with clear ownership (global vs to one entity vs from one entity).
-- You need to inspect, validate, and sometimes cancel or normalize emissions.
+#### Your code probably looks like this
+
+```csharp
+public class Player : MonoBehaviour {
+    public HealthBar healthBar;
+    public AudioManager audio;
+    public AchievementSystem achievements;
+
+    void TakeDamage(int amount) {
+        health -= amount;
+        healthBar.UpdateHealth(health);  // Manual call
+        audio.PlayDamageSound();         // Manual call
+        achievements.CheckDamage(amount); // Manual call
+        // Add analytics? More manual calls...
+    }
+}
+```
+
+**Every new system = another SerializeField + another manual call.** It's exhausting and brittle.
+
+##### DxMessaging fixes this
+
+```csharp
+void TakeDamage(int amount) {
+    health -= amount;
+    new TookDamage(amount).EmitComponentBroadcast(this);
+    // Done! Everything else reacts automatically.
+}
+```
+
+### For Intermediate Devs: "I use C# events but they leak"
+
+#### You know this pain
+
+```csharp
+void OnEnable() { GameManager.OnScoreChanged += UpdateUI; }
+void OnDisable() { /* Forgot this? 💀 LEAK! */ }
+```
+
+**DxMessaging makes leaks impossible** - automatic cleanup when components die.
+
+### For Advanced Devs: "I need observability and control"
+
+- ✅ See message history in Inspector (timestamps, payloads, call counts)
+- ✅ Priority-based execution (no more race conditions)
+- ✅ Interceptors (validate/normalize before handlers)
+- ✅ Global observers (track ALL instances of a message type)
+- ✅ Local bus islands (isolated testing, zero global state)
+
+## What It Solves (Technical)
+
+- **Decoupling without references** - producers/consumers never know about each other
+- **Predictable lifecycle** - explicit tokens tied to Unity component lifecycles
+- **Performance** - struct messages passed by-ref, zero allocations, zero boxing
+- **Observability** - interceptors, post-processors, diagnostics, registration logs
+- **Scalable taxonomy** - three message types (Untargeted/Targeted/Broadcast) cover 99% of use cases
+
+## When to Consider DxMessaging
+
+### Use it when
+
+- You have 3+ systems that need to communicate
+- You've debugged memory leaks from forgotten unsubscribes
+- You're tired of UI depending on 15 different gameplay systems
+- You want to see "what fired when" without setting 50 breakpoints
+- You're building for the long term (months/years, not days)
+
+#### Skip it when
+
+- Game jam prototype (<1 week)
+- Tiny project (<1000 lines)
+- Single-system communication (just call the method directly)
+- You need synchronous return values (DxMessaging is fire-and-forget)
 
 Core ideas
 
@@ -31,15 +98,42 @@ Core ideas
 - Pipeline: Interceptors → Handlers → Post‑Processors, with diagnostics optionally enabled.
 - Unity integration: `MessagingComponent` and `MessageAwareComponent` manage lifecycles cleanly.
 
-Killer features
+## Killer Features (What Makes It Special)
+
+### 🚀 Global Observers: The Unique Advantage
+
+#### Traditional event systems force you to do this
+
+```csharp
+// Subscribe to each entity type separately
+PlayerEvents.OnDamaged += TrackPlayerDamage;
+EnemyEvents.OnDamaged += TrackEnemyDamage;
+NPCEvents.OnDamaged += TrackNPCDamage;
+// Add a new entity type? More subscriptions...
+```
+
+##### DxMessaging lets you do this
+
+```csharp
+// Subscribe ONCE to ALL damage, regardless of source
+_ = Token.RegisterBroadcastWithoutSource<TookDamage>(
+    (InstanceId source, TookDamage msg) => {
+        Analytics.Log($"{source} took {msg.amount} damage");
+    }
+);
+```
+
+**Real-world impact:** Build achievement systems, combat logs, and analytics that work with ANY entity - even ones that don't exist yet.
+
+### Other Killer Features
 
-- **🚀 Global Observers: Listen to ALL messages** — Subscribe to all targeted/broadcast messages of a type without knowing specific targets/sources. **Unlike traditional event buses** where you need separate subscriptions per entity type (PlayerDamaged, EnemyDamaged, etc.), DxMessaging lets you subscribe ONCE to ALL damage events and get the source/target as a parameter. Perfect for analytics, debugging, achievements, and combat logs.
-- **Priority ordering** and explicit pipeline stages (interceptors, handlers, post‑processors).
-- **Local bus islands** for test isolation and modular subsystems.
-- **Struct‑friendly, by‑ref handlers** to avoid boxing and copies.
-- **Attributes + source generation** (`DxAutoConstructor`) reduce boilerplate while keeping strong typing.
-- **Unity‑first helpers** (GameObject/Component emit) and a powerful MessagingComponent inspector.
-- **Global accept‑all** for building inspectors and profilers.
+- **Priority-based ordering** - eliminate race conditions, control execution flow explicitly
+- **Interceptor pipeline** - validate/normalize messages BEFORE handlers run (one validation, all handlers protected)
+- **Local bus islands** - isolated testing with zero global state contamination
+- **Zero-allocation design** - struct messages passed by-ref, no boxing, no GC spikes
+- **Auto-constructor generation** - `[DxAutoConstructor]` eliminates boilerplate while keeping type safety
+- **Unity-first helpers** - `EmitGameObjectTargeted()`, `EmitComponentBroadcast()` feel natural
+- **Inspector diagnostics** - see message history, registrations, call counts in real-time
 
 ---
 

package/Docs/Patterns.md

@@ -1,10 +1,49 @@
-# DxMessaging Patterns
+# DxMessaging Patterns: Real-World Solutions
 
 [← Back to Index](Index.md) | [Getting Started](GettingStarted.md) | [Message Types](MessageTypes.md) | [Samples](../Samples~/)
 
 ---
 
-This document captures practical patterns for building systems with DxMessaging. It complements the README by focusing on composition, structure, and problem-solving techniques.
+**You're here because:** You understand DxMessaging basics, now you want to see "How do I actually build X?"
+
+## What you'll find
+
+- **Basic Patterns** - Fundamental building blocks (scene transitions, commands, observability)
+- **Advanced Patterns** - Power user techniques (diagnostics, testing, legacy integration)
+- **Scale Patterns** - Production-ready examples (100+ entities, cross-scene systems, large UI)
+
+### Reading guide
+
+- **New to DxMessaging?** Start with Basic Patterns 1-8
+- **Intermediate user?** Jump to Advanced Patterns 9-12
+- **Building at scale?** Go straight to Real-World Scale Patterns
+- **Specific problem?** Use Ctrl+F / Cmd+F to search
+
+**Philosophy:** These aren't toy examples. They're patterns from real games with real problems.
+
+---
+
+## Quick Links: "I Want To..."
+
+### Find your use case, jump to the pattern
+
+| I want to...                                 | Go to                                                                                                        |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Make UI react to gameplay                    | [Pattern 2: Directed Commands](#2-directed-commands-targeted)                                                |
+| Coordinate scene transitions                 | [Pattern 1: Scene-wide Events](#1-scene-wide-events-untargeted)                                              |
+| Build an achievement system                  | [Pattern 3: Observability](#3-observability-broadcast) + [Global Accept-All](#10-global-accept-all-handlers) |
+| Validate input/damage before it happens      | [Pattern 4: Interceptors](#4-validation-and-normalization-interceptors)                                      |
+| Add analytics without touching gameplay      | [Pattern 5: Post-Processors](#5-analyticslogging-post-processors)                                            |
+| Track ALL damage from ANY entity             | [Pattern: Managing 100+ Entities](#pattern-managing-100-combat-entities)                                     |
+| Build a large UI system (20+ panels)         | [Pattern: Large-Scale UI](#pattern-large-scale-ui-system-20-panels)                                          |
+| Make systems run in a specific order         | [Pattern: Priority Ordering](#pattern-priority-ordered-execution-for-complex-systems)                        |
+| Test in isolation                            | [Pattern 6: Local Bus Islands](#6-local-bus-islands)                                                         |
+| Migrate from C# events                       | [Pattern 9: Bridging Legacy](#9-bridging-legacy-unity-messaging)                                             |
+| Handle persistent systems across scene loads | [Pattern: Cross-Scene Persistent](#pattern-cross-scene-persistent-systems)                                   |
+| See what's happening (debug message flow)    | [Pattern 11: Diagnostics](#11-diagnostics-and-tuning)                                                        |
+| Build a battle royale / large multiplayer    | [Pattern: Battle Royale Example](#real-world-production-example-battle-royale-game)                          |
+
+---
 
 ## Table of Contents