com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/{Docs/InterceptorsAndOrdering.md → docs/concepts/interceptors-and-ordering.md}

@@ -23,10 +23,12 @@ _ = token.RegisterUntargeted<GameEvent>(msg => {
 });
 
 // First emission: only the original handler runs
-new GameEvent().Emit();  // DoWork() executes, ProcessLater() does NOT
+var firstEvent = new GameEvent();
+firstEvent.Emit();  // DoWork() executes, ProcessLater() does NOT
 
 // Second emission: both handlers run
-new GameEvent().Emit();  // Both DoWork() and ProcessLater() execute
+var secondEvent = new GameEvent();
+secondEvent.Emit();  // Both DoWork() and ProcessLater() execute
 ```
 
 ##### Why this matters
@@ -36,7 +38,7 @@ new GameEvent().Emit();  // Both DoWork() and ProcessLater() execute
 - Ensures all listeners see a consistent view of the registration state
 - Makes debugging and reasoning about message flow easier
 
-This snapshot behavior is extensively tested in the [Mutation During Emission tests](../Tests/Runtime/Core/MutationDuringEmissionTests.cs).
+This snapshot behavior is extensively tested in the [Mutation During Emission tests](https://github.com/wallstop/DxMessaging/blob/master/Tests/Runtime/Core/MutationDuringEmissionTests.cs).
 
 ---
 
@@ -82,57 +84,49 @@ Notes on handler groups
 Visual overview
 
 ```mermaid
+%%{init: {'theme': 'neutral'}}%%
 flowchart LR
-  subgraph Untargeted["<b>Untargeted Messages</b>"]
+  subgraph Untargeted["Untargeted Messages"]
     direction TB
-    U1["Interceptors&lt;T&gt;"] --> U2[Global Accept‑All Untargeted]
-    U2 --> U3["Handlers&lt;T&gt;"]
-    U3 --> U4["Post‑Processors&lt;T&gt;"]
+    U1["Interceptors(T)"] --> U2[Global Accept‑All Untargeted]
+    U2 --> U3["Handlers(T)"]
+    U3 --> U4["Post‑Processors(T)"]
   end
 
-  subgraph Targeted["<b>Targeted Messages</b>"]
+  subgraph Targeted["Targeted Messages"]
     direction TB
-    T1["Interceptors&lt;T&gt;"] --> T2[Global Accept‑All Targeted]
-    T2 --> T3["Handlers&lt;T&gt; @ target"]
-    T3 --> T4["Handlers&lt;T&gt; (All Targets)"]
-    T4 --> T5["Post‑Processors&lt;T&gt; @ target"]
-    T5 --> T6["Post‑Processors&lt;T&gt; (All Targets)"]
+    T1["Interceptors(T)"] --> T2[Global Accept‑All Targeted]
+    T2 --> T3["Handlers(T) @ target"]
+    T3 --> T4["Handlers(T) (All Targets)"]
+    T4 --> T5["Post‑Processors(T) @ target"]
+    T5 --> T6["Post‑Processors(T) (All Targets)"]
   end
 
-  subgraph Broadcast["<b>Broadcast Messages</b>"]
+  subgraph Broadcast["Broadcast Messages"]
     direction TB
-    B1["Interceptors&lt;T&gt;"] --> B2[Global Accept‑All Broadcast]
-    B2 --> B3["Handlers&lt;T&gt; @ source"]
-    B3 --> B4["Handlers&lt;T&gt; (All Sources)"]
-    B4 --> B5["Post‑Processors&lt;T&gt; @ source"]
-    B5 --> B6["Post‑Processors&lt;T&gt; (All Sources)"]
+    B1["Interceptors(T)"] --> B2[Global Accept‑All Broadcast]
+    B2 --> B3["Handlers(T) @ source"]
+    B3 --> B4["Handlers(T) (All Sources)"]
+    B4 --> B5["Post‑Processors(T) @ source"]
+    B5 --> B6["Post‑Processors(T) (All Sources)"]
   end
 
-  style Untargeted fill:#f0f0f0,stroke:#666,stroke-width:2px,color:#000
-  style Targeted fill:#f0f0f0,stroke:#666,stroke-width:2px,color:#000
-  style Broadcast fill:#f0f0f0,stroke:#666,stroke-width:2px,color:#000
-
-  style U1 fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
-  style U2 fill:#d3adf7,stroke:#531dab,stroke-width:2px,color:#000
-  style U3 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-  style U4 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
-  style T1 fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
-  style T2 fill:#d3adf7,stroke:#531dab,stroke-width:2px,color:#000
-  style T3 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-  style T4 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-  style T5 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
-  style T6 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
-  style B1 fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
-  style B2 fill:#d3adf7,stroke:#531dab,stroke-width:2px,color:#000
-  style B3 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-  style B4 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-  style B5 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
-  style B6 fill:#95de64,stroke:#237804,stroke-width:2px,color:#000
+  classDef neutral stroke-width:2px
+  class Untargeted,Targeted,Broadcast neutral
+  classDef warning stroke-width:2px
+  class U1,T1,B1 warning
+  classDef accent stroke-width:2px
+  class U2,T2,B2 accent
+  classDef primary stroke-width:2px
+  class U3,T3,T4,B3,B4 primary
+  classDef success stroke-width:2px
+  class U4,T5,T6,B5,B6 success
 ```
 
 Example sequence
 
 ```mermaid
+%%{init: {'theme': 'neutral'}}%%
 sequenceDiagram
     participant P as Producer
     participant I as Interceptor(s)
@@ -171,7 +165,7 @@ _ = bus.RegisterTargetedInterceptor<TookDamage>(
 
 Real‑World Use Cases
 
-###### State‑Based Message Cancellation
+#### State‑Based Message Cancellation
 
 Prevent UI messages from being processed based on current UI state:
 
@@ -224,11 +218,13 @@ var uiManager = new UIStateManager();
 uiManager.RegisterInterceptors();
 uiManager.EnterCutscene();
 
-new OpenMenu("inventory").Emit();  // Cancelled by interceptor
-new ShowDialog("Hello!").Emit();   // Cancelled by interceptor
+var openMenu = new OpenMenu("inventory");
+openMenu.Emit();  // Cancelled by interceptor
+var showDialog = new ShowDialog("Hello!");
+showDialog.Emit();  // Cancelled by interceptor
 ```
 
-###### Value Clamping and Normalization
+#### Value Clamping and Normalization
 
 Ensure message data stays within valid ranges:
 
@@ -275,11 +271,12 @@ var normalizer = new InputNormalizer();
 normalizer.RegisterInterceptors();
 
 // Even invalid input gets cleaned
-new MovementInput(new Vector2(100, 200), 9999f).Emit();
+var input = new MovementInput(new Vector2(100, 200), 9999f);
+input.Emit();
 // Handlers receive: direction=(0.45, 0.89), speed=10.0
 ```
 
-###### Permission and Authorization Checks
+#### Permission and Authorization Checks
 
 Block messages that violate game rules or permissions:
 
@@ -349,13 +346,15 @@ var permissions = new PermissionSystem(playerDataService);
 permissions.RegisterInterceptors();
 
 // This will be blocked if player doesn't have 100 currency
-new SpendCurrency(100).EmitTargeted(playerId);
+var spendCurrency = new SpendCurrency(100);
+spendCurrency.EmitTargeted(playerId);
 
 // This will be blocked if achievement is already unlocked
-new UnlockAchievement("first_boss").EmitTargeted(playerId);
+var unlockAchievement = new UnlockAchievement("first_boss");
+unlockAchievement.EmitTargeted(playerId);
 ```
 
-###### Message Enrichment and Context Addition
+#### Message Enrichment and Context Addition
 
 Add contextual data to messages as they flow through the system:
 
@@ -410,11 +409,12 @@ var enricher = new TelemetryEnricher(Guid.NewGuid().ToString());
 enricher.RegisterInterceptors();
 
 // Emit without timestamp/session - interceptor adds them
-new PlayerAction("jump").EmitTargeted(playerId);
+var action = new PlayerAction("jump");
+action.EmitTargeted(playerId);
 // Handlers receive fully enriched message with timestamp and sessionId
 ```
 
-###### Cooldown and Rate Limiting
+#### Cooldown and Rate Limiting
 
 Prevent message spam by enforcing cooldowns:
 
@@ -467,10 +467,13 @@ public class CooldownManager
 var cooldowns = new CooldownManager();
 cooldowns.RegisterInterceptors();
 
-new CastSpell("fireball").EmitTargeted(playerId);  // ✓ Allowed
-new CastSpell("fireball").EmitTargeted(playerId);  // ✗ Blocked (too soon)
+var spell1 = new CastSpell("fireball");
+spell1.EmitTargeted(playerId);  // ✓ Allowed
+var spell2 = new CastSpell("fireball");
+spell2.EmitTargeted(playerId);  // ✗ Blocked (too soon)
 // ... wait 1.5s ...
-new CastSpell("fireball").EmitTargeted(playerId);  // ✓ Allowed
+var spell3 = new CastSpell("fireball");
+spell3.EmitTargeted(playerId);  // ✓ Allowed
 ```
 
 When to Use Interceptors
@@ -517,5 +520,5 @@ Global Accept‑All
 
 Related
 
-- [Message Types](MessageTypes.md)
-- [Listening Patterns](ListeningPatterns.md)
+- [Message Types](message-types.md)
+- [Listening Patterns](listening-patterns.md)

package/docs/concepts/interceptors-and-ordering.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 8723cdfcb0ffc734dbb2011c4ec5b004
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/{Docs/ListeningPatterns.md → docs/concepts/listening-patterns.md}

@@ -1,6 +1,6 @@
 # Listening Patterns
 
-Targeted across all targets
+## Targeted across all targets
 
 - Accept every targeted message of a given type regardless of who it’s for.
 
@@ -10,14 +10,14 @@ using DxMessaging.Core.Messages;
 
 // Observe all Heal messages and their intended targets
 _ = token.RegisterTargetedWithoutTargeting<Heal>(OnAnyHeal);
-void OnAnyHeal(ref InstanceId target, ref Heal m) => Audit(target, m);
+void OnAnyHeal(InstanceId target, Heal m) => Audit(target, m);
 
 // Post‑process all targeted of type
 _ = token.RegisterTargetedWithoutTargetingPostProcessor<Heal>(OnAnyHealPost);
-void OnAnyHealPost(ref InstanceId target, ref Heal m) => Log(target, m);
+void OnAnyHealPost(InstanceId target, Heal m) => Log(target, m);
 ```
 
-Broadcast across all sources
+## Broadcast across all sources
 
 - Accept every broadcast message of a given type regardless of who emitted it.
 
@@ -27,14 +27,14 @@ using DxMessaging.Core.Messages;
 
 // Observe all TookDamage messages and their sources
 _ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyTookDamage);
-void OnAnyTookDamage(ref InstanceId source, ref TookDamage m) => Track(source, m);
+void OnAnyTookDamage(InstanceId source, TookDamage m) => Track(source, m);
 
 // Post‑process all broadcast of type
 _ = token.RegisterBroadcastWithoutSourcePostProcessor<TookDamage>(OnAnyTookDamagePost);
 void OnAnyTookDamagePost(InstanceId source, TookDamage m) => Log(source, m);
 ```
 
-Global accept‑all (debug/inspection)
+## Global accept‑all (debug/inspection)
 
 - Receive every message of every type on a handler; useful for tooling.
 
@@ -47,9 +47,9 @@ var dereg = bus.RegisterGlobalAcceptAll(handler);
 // implement handler callbacks for generic categories on your MessageHandler
 ```
 
-Real‑World Use Cases
+## Real‑World Use Cases
 
-## Development Debug Dump
+### Development Debug Dump
 
 Capture all messages during development for debugging and diagnostics:
 
@@ -172,12 +172,14 @@ public class NetworkReplicator : MessageHandler
 var replicator = new NetworkReplicator(networkManager) { active = true };
 _ = MessageHandler.MessageBus.RegisterGlobalAcceptAll(replicator);
 
-// These messages now "just work" across the network
-new PlayerMoved(playerPos).Emit();
-new DealDamage(50f).EmitTargeted(enemyId);
+// These messages are now replicated across the network
+var playerMoved = new PlayerMoved(playerPos);
+playerMoved.Emit();
+var dealDamage = new DealDamage(50f);
+dealDamage.EmitTargeted(enemyId);
 ```
 
-#### Message Analytics and Metrics
+### Message Analytics and Metrics
 
 Track message frequency and performance across your entire game:
 
@@ -245,7 +247,7 @@ When to Use Global Accept‑All
 - Message replay/recording systems
 
 ⚠️ **Performance consideration:**
-Global Accept‑All handlers are invoked for **every** message of **every** type. For high‑performance gameplay logic, prefer type‑specific registrations which use O(1) lookup instead of O(N) iteration.
+Global Accept-All handlers are invoked for **every** message of **every** type. For performance-sensitive gameplay logic, prefer type-specific registrations which use O(1) lookup instead of O(N) iteration.
 
 ❌ **Avoid for:**
 
@@ -260,5 +262,5 @@ Tips
 
 Related
 
-- [Interceptors & Ordering](InterceptorsAndOrdering.md)
-- [Diagnostics](Diagnostics.md)
+- [Interceptors & Ordering](interceptors-and-ordering.md)
+- [Diagnostics](../guides/diagnostics.md)

package/docs/concepts/listening-patterns.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: aac4e4e26504c5a4cb3dc9eab5d68be2
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/{Docs/MessageTypes.md → docs/concepts/message-types.md}

@@ -1,6 +1,6 @@
 # Message Types: When and How to Use
 
-[← Back to Index](Index.md) | [Getting Started](GettingStarted.md) | [Patterns](Patterns.md) | [Visual Guide](VisualGuide.md)
+[← Back to Index](../getting-started/index.md) | [Getting Started](../getting-started/getting-started.md) | [Patterns](../guides/patterns.md) | [Visual Guide](../getting-started/visual-guide.md)
 
 ---
 
@@ -15,6 +15,7 @@ This guide introduces the three message categories in DxMessaging with concepts,
 ### Quick Decision Guide
 
 ```mermaid
+%%{init: {'theme': 'neutral'}}%%
 flowchart TD
     Start([Choose Message Type])
 
@@ -32,11 +33,16 @@ flowchart TD
 
     Q3 -->|No| Rethink[🤔 Rethink your<br/>message design]
 
-    style Untargeted fill:#91d5ff,stroke:#096dd9,stroke-width:3px,color:#000
-    style Targeted fill:#ffd591,stroke:#d46b08,stroke-width:3px,color:#000
-    style Broadcast fill:#95de64,stroke:#237804,stroke-width:3px,color:#000
-    style Rethink fill:#ffa39e,stroke:#cf1322,stroke-width:2px,color:#000
-    style Start fill:#f0f0f0,stroke:#595959,stroke-width:2px,color:#000
+    classDef primary stroke-width:3px
+    class Untargeted primary
+    classDef warning stroke-width:3px
+    class Targeted warning
+    classDef success stroke-width:3px
+    class Broadcast success
+    classDef danger stroke-width:2px
+    class Rethink danger
+    classDef neutral stroke-width:2px
+    class Start,Q1,Q2,Q3 neutral
 ```
 
 ## Untargeted Messages
@@ -198,16 +204,16 @@ void OnAnyTookDamage(ref InstanceId source, ref TookDamage m) => Track(source, m
 
 ### Prerequisites
 
-- → [Getting Started](GettingStarted.md) — Understand the basics first
-- → [Visual Guide](VisualGuide.md) — See the 3 types visualized
+- → [Getting Started](../getting-started/getting-started.md) — Understand the basics first
+- → [Visual Guide](../getting-started/visual-guide.md) — See the 3 types visualized
 
 #### Next Steps
 
-- → [Patterns](Patterns.md) — Real-world examples of each type
-- → [Listening Patterns](ListeningPatterns.md) — All the ways to receive messages
-- → [Interceptors & Ordering](InterceptorsAndOrdering.md) — Control message flow
+- → [Patterns](../guides/patterns.md) — Real-world examples of each type
+- → [Listening Patterns](listening-patterns.md) — All the ways to receive messages
+- → [Interceptors & Ordering](interceptors-and-ordering.md) — Control message flow
 
 ##### Try It
 
-- → [Quick Start](QuickStart.md) — Working example
-- → [Mini Combat sample](../Samples~/Mini%20Combat/README.md) — See all 3 types in action
+- → [Quick Start](../getting-started/quick-start.md) — Working example
+- → [Mini Combat sample](https://github.com/wallstop/DxMessaging/blob/master/Samples~/Mini%20Combat/README.md) — See all 3 types in action

package/docs/concepts/message-types.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: c60a113c88b589949addd17450bbacef
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/{Docs/TargetingAndContext.md → docs/concepts/targeting-and-context.md}

@@ -161,9 +161,9 @@ damage.EmitAt(this);  // ✅ Works!
 
 ## Listening to ALL Events (Global Observers)
 
-**🚀 Killer Feature:** Unlike traditional event buses, DxMessaging lets you listen to ALL targeted or broadcast messages **without knowing the specific target or source**.
+**Feature:** DxMessaging allows listening to all targeted or broadcast messages **without knowing the specific target or source**.
 
-This is a game-changer for:
+This is useful for:
 
 - **Analytics** — Track every action in your game without coupling to individual objects
 - **Debugging** — See all events of a type in one place
@@ -197,7 +197,7 @@ void OnBossDamaged(int amount) { RecordDamage("Boss", amount); }
 ### DxMessaging Global Observer Pattern
 
 ```csharp
-// ✅ DxMessaging: One subscription, zero coupling, infinite scalability
+// ✅ DxMessaging: One subscription, zero coupling
 _ = token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyDamage);
 
 void OnAnyDamage(ref InstanceId source, ref TookDamage msg)
@@ -205,7 +205,7 @@ void OnAnyDamage(ref InstanceId source, ref TookDamage msg)
     // Works for Player, Enemy, NPC, Boss, and any future entity type!
     RecordDamage(source, msg.amount);
 }
-// Add new entity? Zero changes needed. It just works.
+// Add new entity? Zero changes needed.
 ```
 
 ### Listening to All Targeted Messages
@@ -429,7 +429,7 @@ heal.EmitAt(gameObject);  // Both GameObject
 1. Registration happened after emission
 1. Using wrong bus (local vs global)
 
-See [Troubleshooting](Troubleshooting.md) for more debugging tips.
+See [Troubleshooting](../reference/troubleshooting.md) for more debugging tips.
 
 ## Quick Reference
 
@@ -444,8 +444,8 @@ See [Troubleshooting](Troubleshooting.md) for more debugging tips.
 
 ## See Also
 
-- **[Emit Shorthands](EmitShorthands.md)** — Concise ways to emit messages
-- **[Message Types](MessageTypes.md)** — Understanding Untargeted, Targeted, and Broadcast
-- **[Unity Integration](UnityIntegration.md)** — MessageAwareComponent and lifecycle
-- **[Quick Reference](QuickReference.md)** — API cheat sheet
-- **[Troubleshooting](Troubleshooting.md)** — Solving common issues
+- **[Emit Shorthands](../advanced/emit-shorthands.md)** — Concise ways to emit messages
+- **[Message Types](message-types.md)** — Understanding Untargeted, Targeted, and Broadcast
+- **[Unity Integration](../guides/unity-integration.md)** — MessageAwareComponent and lifecycle
+- **[Quick Reference](../reference/quick-reference.md)** — API cheat sheet
+- **[Troubleshooting](../reference/troubleshooting.md)** — Solving common issues

package/docs/concepts/targeting-and-context.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: f0c2c3d64071ab54fbf7b63ad29ee73c
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/docs/concepts.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: e56d6159c592de94e93c4f017c76b4c0
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/docs/examples/end-to-end-scene-transitions.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 153c32b66e21f1745a9c485ae554a74b
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/{Docs/EndToEnd.md → docs/examples/end-to-end.md}

@@ -135,5 +135,5 @@ Diagnostics (Editor)
 
 Notes
 
-- Use component vs gameObject context consistently for targeted/broadcast messages (see [Targeting & Context](TargetingAndContext.md)).
+- Use component vs gameObject context consistently for targeted/broadcast messages (see [Targeting & Context](../concepts/targeting-and-context.md)).
 - For tests/subsystems, use a local MessageBus and pass it to the token factory.

package/docs/examples/end-to-end.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: b088debe46ca9ac4c889dc61365a5005
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/docs/examples.meta

@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: cc6f2285685cc9545ab538b1e21b1681
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/{Docs/GettingStarted.md → docs/getting-started/getting-started.md}

@@ -1,12 +1,12 @@
 # Getting Started with DxMessaging
 
-[← Back to Index](Index.md) | [Visual Guide](VisualGuide.md) | [Quick Start](QuickStart.md) | [FAQ](FAQ.md)
+[Back to Index](index.md) | [Visual Guide](visual-guide.md) | [Quick Start](quick-start.md) | [FAQ](../reference/faq.md)
 
 ---
 
-Welcome! This guide will take you from zero to productive with DxMessaging in about 10 minutes. By the end, you'll understand what DxMessaging is, why it's powerful, and how to use it effectively in your Unity projects.
+This guide covers the basics of DxMessaging. By the end, you'll understand what DxMessaging is, when it might be useful, and how to use it in your Unity projects.
 
-## 🎯 Your Goal
+## Your Goal
 
 By the end of this guide, you will:
 
@@ -36,22 +36,22 @@ By the end of this guide, you will:
 - Check if an achievement unlocked
 - Maybe trigger a tutorial tip
 
-**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.
+**One approach:** The Player script needs references to all 6 systems. Or they all need references to the Player. This can create tight coupling.
 
-**The DxMessaging way:** The Player emits one message: `TookDamage(25)`. Everyone who cares receives it automatically. Zero coupling, zero leaks, zero hassle.
+**With DxMessaging:** The Player emits one message: `TookDamage(25)`. Interested systems receive it through subscriptions. This approach decouples systems and handles cleanup automatically.
 
 ---
 
-**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.
+**Technical summary:** DxMessaging is a type-safe messaging system that provides an alternative to C# events, UnityEvents, and global event buses.
 
-**Think of it as:** The event system Unity should have shipped with.
+**Think of it as:** An alternative event system designed for larger projects.
 
 ### What you get
 
-- **Decoupled systems** - no manual subscribe/unsubscribe, impossible to leak
+- **Decoupled systems** - no manual subscribe/unsubscribe, leak prevention built-in
 - **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
+- **Designed to scale** - works for prototypes and larger codebases
 
 ## Quick Start
 
@@ -113,13 +113,13 @@ heal.EmitGameObjectTargeted(playerGameObject);
 
 ```text
 Is it a global announcement? (pause, settings, scene load)
-  → Use UNTARGETED
+  -> Use UNTARGETED
 
 Are you commanding a specific entity? (heal Player, open Chest #3)
-  → Use TARGETED
+  -> Use TARGETED
 
 Is an entity announcing something happened? (Enemy died, Chest opened)
-  → Use BROADCAST
+  -> Use BROADCAST
 ```
 
 #### Examples
@@ -138,11 +138,11 @@ public struct Heal { public int amount; }
 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.
+**Need more detail?** See the [Visual Guide](visual-guide.md) for additional explanations, or [Message Types](../concepts/message-types.md) for technical details.
 
 ## Common Patterns
 
-### Want to see real examples? Here's what DxMessaging excels at
+### Example use cases
 
 - **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
@@ -150,42 +150,42 @@ public struct EnemyDied { public string enemyName; }
 - **Input handling** - Decouple input system from player controller
 - **Analytics** - Track all events without polluting gameplay code
 
-**Want code examples?** See [Patterns](Patterns.md) for production-ready patterns and [ListeningPatterns](ListeningPatterns.md) for advanced techniques.
+**Want code examples?** See [Patterns](../guides/patterns.md) for example patterns and [Listening Patterns](../concepts/listening-patterns.md) for additional techniques.
 
 ## Troubleshooting
 
-### "My handler isn't being called!"
+### "My handler isn't being called"
 
-✅ Checklist:
+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!"
+### "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]`"
+### "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?"
+### "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
 
-**Still stuck?** See [Troubleshooting](Troubleshooting.md) for the complete guide or [FAQ](FAQ.md) for common questions.
+**Still stuck?** See [Troubleshooting](../reference/troubleshooting.md) for the complete guide or [FAQ](../reference/faq.md) for common questions.
 
 ## Next Steps
 
-- [Visual Guide](VisualGuide.md)
-- [Quick Reference](QuickReference.md)
-- [Diagnostics](Diagnostics.md)
-- [Interceptors and Ordering](InterceptorsAndOrdering.md)
+- [Visual Guide](visual-guide.md)
+- [Quick Reference](../reference/quick-reference.md)
+- [Diagnostics](../guides/diagnostics.md)
+- [Interceptors and Ordering](../concepts/interceptors-and-ordering.md)
 
 ## Quick Reference
 
@@ -194,7 +194,9 @@ public struct EnemyDied { public string enemyName; }
 _ = Token.RegisterBroadcastWithoutSource<TookDamage>(OnAnyDamage);
 _ = Token.RegisterGameObjectTargeted<Heal>(playerGO, OnPlayerHealed);
 
-// Emit
-new TookDamage(25).EmitBroadcastWithoutSource();
-new Heal(10).EmitGameObjectTargeted(playerGO);
+// Emit (broadcasts always require a source)
+var damage = new TookDamage(25);
+damage.EmitGameObjectBroadcast(enemyGO);  // enemyGO is the source
+var heal = new Heal(10);
+heal.EmitGameObjectTargeted(playerGO);
 ```

package/docs/getting-started/getting-started.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 4cac18b84476a9b45be51b63137fff51
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: