Address documentation review feedback

- Fix escaped \< in headings (data-stores, tcp-udp)
- Fix log level usage: use log<WARN> inside reactors, NUClear::LogLevel::WARN outside
- Expand logging how-to with system architecture, custom handlers, display_level
- Fix 'thinking out loud' text in periodic-tasks tutorial
- Add CSS fix for inline code angle bracket spacing
- Expand networking how-to for broadcast/unicast/multicast modes
- Fix reliable delivery: guarantees delivery but not order
- Add watchdog tip: use Reactor type itself as group
- Fix sync mermaid diagram: scheduler as first column
- Add Always shutdown warning: don't block forever
- Reorder tracing how-to: install TraceController before usage
- Add thread context table to extending-dsl guide
- Improve architecture explanation hierarchy

Author: TrentHouliston

docs2/explanation/architecture.md

@@ -129,11 +129,14 @@ graph TB
     S -->|dispatch| TP3
 ```
 
-The **PowerPlant** is the container for the entire system. It:
+The hierarchy is straightforward:
 
-- Holds all **Reactors** (your components)
-- Reactors register **Reactions** (event handlers declared with `on<>().then()`)
-- When data is emitted, the **Scheduler** creates tasks and dispatches them to **Thread Pools**
+- A **PowerPlant** is the top-level container for the entire system
+- A PowerPlant contains **Reactors** — your self-contained components
+- Each Reactor declares **Reactions** — event handlers registered with `on<>().then()`
+- When a Reaction runs, it can **emit messages** that trigger other Reactions
+
+This creates a data-driven execution model: components don't call each other directly. Instead, they emit data, and the scheduler dispatches reactions in response.
 
 ## Design Philosophy
 

docs2/how-to/extending-dsl.md

@@ -58,7 +58,7 @@ struct LogTiming {
         auto us = std::chrono::duration_cast<std::chrono::microseconds>(elapsed).count();
 
         if (us > 1000) {  // Only log if > 1ms
-            NUClear::log<NUClear::WARN>("Slow reaction:",
+            NUClear::log<NUClear::LogLevel::WARN>("Slow reaction:",
                                          task.reaction->identifiers->name,
                                          "took", us, "µs");
         }
@@ -190,9 +190,26 @@ The Fusion Engine walks the inheritance tree and collects all extension points f
 
 See [Extension Points Reference](../reference/extensions/extension-points.md) and [Fusion Engine](../reference/extensions/fusion-engine.md) for full details.
 
+## Thread Context
+
+Different extension points run in different thread contexts. This is critical to understand when using `thread_local` storage or sharing state:
+
+| Point          | Runs on                                     | Notes                                              |
+| -------------- | ------------------------------------------- | -------------------------------------------------- |
+| `bind`         | The thread that calls `on<>()`              | Usually the main thread during reactor construction |
+| `get`          | The thread that **created** the task        | Often different from the execution thread          |
+| `precondition` | The thread that **created** the task        | Same thread as `get`                               |
+| `pre_run`      | The **execution** thread                    | Same thread as the callback                        |
+| `post_run`     | The **execution** thread                    | Same thread as the callback                        |
+| `scope`        | The **execution** thread                    | RAII object lives for callback duration            |
+
+!!! warning "thread_local in get vs pre_run/post_run"
+    Because `get` runs on the task-creation thread (not the execution thread), `thread_local` variables set in `get` will **not** be visible in `pre_run`, `post_run`, or the callback itself. If you need per-execution state, use `pre_run`/`post_run` or the `scope` extension point, which provides RAII objects that persist for the lifetime of the reaction execution.
+
 ## Tips
 
 - Words are never instantiated — delete the constructor to make this clear.
-- Use `thread_local` storage for per-execution state in `pre_run`/`post_run`.
+- Use `thread_local` storage for per-execution state in `pre_run`/`post_run` only — not in `get`.
+- Use the `scope` extension point if you need state that persists across the reaction execution with RAII semantics.
 - Template parameters on your word become compile-time configuration (like `RateLimit<10, seconds>`).
 - Test custom words the same way you test any reactor — single-threaded plant with assertions.

docs2/how-to/logging.md

@@ -135,4 +135,97 @@ public:
 
 !!! note "Default log level"
 
-    Reactors default to `log_level = INFO`. Set it in your constructor to change the threshold.
+    Reactors default to `log_level = DEBUG`. Set it in your constructor to change the threshold.
+
+## How the Log System Works
+
+```mermaid
+sequenceDiagram
+    participant R as Reactor
+    participant P as PowerPlant
+    participant H as Log Handler Reactions
+
+    R->>R: log<WARN>("message")
+    Note over R: Check: WARN >= reactor.log_level?
+    R->>P: Emit LogMessage
+    P->>H: Trigger all on<Trigger<LogMessage>> reactions
+    Note over H: Handler decides what to display/store
+```
+
+The log system is entirely message-driven:
+
+1. A `log<Level>(...)` call in a reactor checks whether `Level` meets the reactor's `log_level` threshold
+2. If it passes, a `LogMessage` is emitted into the system
+3. Any reaction bound to `Trigger<LogMessage>` receives it
+4. **Without a log handler installed, no output appears** — you must install a reactor that handles `LogMessage`
+
+### Per-Reactor vs System Log Level
+
+There are two filtering levels:
+
+- **`log_level`** (per-reactor) — set in each reactor's constructor. Messages below this level are not emitted by that reactor.
+- **`min_log_level`** (system-wide) — set in `NUClear::Configuration`. Messages below this level are discarded regardless of the reactor's setting.
+
+A message is emitted only if its level meets **both** thresholds.
+
+### The `display_level` Field
+
+Each `LogMessage` carries a `display_level` field equal to the emitting reactor's `log_level`. This allows handlers to implement display filtering — a handler can choose to only display messages where `msg.level >= msg.display_level`, letting each reactor control its own verbosity without affecting other reactors.
+
+## Writing Custom Log Handlers
+
+Since log handling is just a reaction to `LogMessage`, you can write handlers that log to files, send to a network service, buffer output, or anything else:
+
+### File Logger
+
+```cpp
+#include <nuclear>
+#include <fstream>
+
+class FileLogger : public NUClear::Reactor {
+public:
+    explicit FileLogger(std::unique_ptr<NUClear::Environment> environment) : Reactor(std::move(environment)) {
+
+        on<Trigger<NUClear::message::LogMessage>>().then([this](const NUClear::message::LogMessage& msg) {
+            if (msg.level >= msg.display_level) {
+                file << "[" << msg.level << "] "
+                     << msg.reactor_name << ": "
+                     << msg.message << "\n";
+                file.flush();
+            }
+        });
+    }
+
+private:
+    std::ofstream file{"application.log"};
+};
+```
+
+### Filtered Handler
+
+You can create handlers that only process certain severity levels:
+
+```cpp
+class ErrorReporter : public NUClear::Reactor {
+public:
+    explicit ErrorReporter(std::unique_ptr<NUClear::Environment> environment) : Reactor(std::move(environment)) {
+
+        on<Trigger<NUClear::message::LogMessage>>().then([this](const NUClear::message::LogMessage& msg) {
+            if (msg.level >= ERROR) {
+                // Send errors to external monitoring
+                send_to_monitoring_service(msg.message);
+            }
+        });
+    }
+};
+```
+
+### Logging from Outside a Reactor
+
+If you need to log from code that isn't inside a reactor (e.g., a utility function called from `main()`), use the free function with full qualification:
+
+```cpp
+NUClear::log<NUClear::LogLevel::INFO>("Starting up...");
+```
+
+This requires a PowerPlant to be running. The message will have no associated reactor name.

docs2/how-to/networking.md

@@ -52,12 +52,57 @@ public:
 | Field              | Type       | Default            | Description                                      |
 | ------------------ | ---------- | ------------------ | ------------------------------------------------ |
 | `name`             | `string`   | —                  | Unique name for this node on the network         |
-| `announce_address` | `string`   | —                  | Multicast address for node discovery             |
+| `announce_address` | `string`   | —                  | Address for node discovery announcements         |
 | `announce_port`    | `uint16_t` | —                  | Port for announce messages                       |
 | `bind_address`     | `string`   | `""` (all)         | Local interface to bind to                       |
-| `mtu`              | `uint16_t` | `1500`             | Maximum transmission unit (fragments if larger)  |
+| `mtu`             | `uint16_t` | `1500`             | Maximum transmission unit (fragments if larger)  |
 
-The default multicast address `239.226.152.162` with port `7447` is a conventional choice for LAN discovery. All nodes that share the same announce address and port will discover each other.
+### Network Modes
+
+NUClearNet supports several discovery modes depending on the `announce_address` you configure:
+
+| Mode | Address Type | Example | Use Case |
+|------|-------------|---------|----------|
+| **Multicast IPv4** | `239.x.x.x` | `239.226.152.162` | LAN discovery, multiple nodes |
+| **Multicast IPv6** | `ff02::x` | `ff02::1` | IPv6 LAN discovery |
+| **Broadcast IPv4** | `x.x.x.255` | `192.168.1.255` | Simple LAN, all nodes on subnet |
+| **Unicast IPv4/IPv6** | Specific IP | `192.168.1.50` | Point-to-point, two nodes |
+
+#### Multicast (Default)
+
+Multicast is the most common mode. All nodes join a multicast group and discover each other automatically:
+
+```cpp
+emit(std::make_unique<NUClear::message::NetworkConfiguration>(
+    "my-node", "239.226.152.162", 7447));
+```
+
+The default multicast address `239.226.152.162` with port `7447` is a conventional choice. All nodes that share the same announce address and port will discover each other.
+
+#### Broadcast
+
+For simpler networks, use a broadcast address. All nodes on the subnet will receive announce messages:
+
+```cpp
+emit(std::make_unique<NUClear::message::NetworkConfiguration>(
+    "my-node", "192.168.1.255", 7447));
+```
+
+#### Unicast (Point-to-Point)
+
+For direct connections between exactly two nodes, use unicast. Each node sets its announce address to the other node's IP:
+
+```cpp
+// On Node A (IP: 192.168.1.10)
+emit(std::make_unique<NUClear::message::NetworkConfiguration>(
+    "node-a", "192.168.1.20", 7447));  // Point to Node B
+
+// On Node B (IP: 192.168.1.20)
+emit(std::make_unique<NUClear::message::NetworkConfiguration>(
+    "node-b", "192.168.1.10", 7447));  // Point to Node A
+```
+
+In unicast mode, each peer announces directly to the other. This is useful when multicast/broadcast is unavailable (e.g., across subnets or VPNs).
 
 ## 2. Send Messages
 
@@ -180,7 +225,7 @@ public:
 | Mode         | Behavior                                                     | Use when                          |
 | ------------ | ------------------------------------------------------------ | --------------------------------- |
 | Unreliable   | Fire-and-forget. No retransmission. Lowest latency.          | Streaming data, periodic updates  |
-| Reliable     | Retransmits until acknowledged. Ordered delivery guaranteed. | Commands, configuration, events   |
+| Reliable     | Retransmits until acknowledged. Delivery guaranteed.         | Commands, configuration, events   |
 
 Pass `true` as the reliability argument to `emit<Scope::NETWORK>`:
 

docs2/how-to/synchronization.md

@@ -76,12 +76,12 @@ private:
 
 ```mermaid
 sequenceDiagram
-    participant T1 as Task A (Sync<X>)
     participant S as Scheduler
+    participant T1 as Task A (Sync<X>)
     participant T2 as Task B (Sync<X>)
     participant T3 as Task C (Sync<X>)
 
-    T1->>S: Start executing
+    S->>T1: Execute
     T2->>S: Request execution
     Note over S: X is locked, queue B
     T3->>S: Request execution

docs2/how-to/tcp-udp.md

@@ -2,7 +2,7 @@
 
 > How to use raw TCP and UDP sockets to talk to non-NUClear systems.
 
-## When to Use This vs Network\<T\>
+## When to Use This vs Network&lt;T&gt;
 
 | Feature | `Network<T>` | `TCP` / `UDP` |
 |---------|-------------|---------------|

docs2/how-to/tracing.md

@@ -7,6 +7,27 @@ NUClear includes a built-in tracing system that records reaction execution, sche
 - The `TraceController` extension must be installed in your PowerPlant
 - The output `.trace` file can be viewed in [Perfetto UI](https://ui.perfetto.dev/) or Chrome's `chrome://tracing`
 
+## Installing the TraceController
+
+The `TraceController` must be installed before you can start tracing. Add it to your PowerPlant setup:
+
+```cpp
+#include <nuclear>
+
+int main(int argc, const char* argv[]) {
+    NUClear::Configuration config;
+    NUClear::PowerPlant plant(config, argc, argv);
+
+    // Install the trace controller
+    plant.install<NUClear::extension::TraceController>();
+
+    // Install your reactors
+    plant.install<MyApp>();
+
+    plant.start();
+}
+```
+
 ## Starting a Trace
 
 To begin recording, emit a `BeginTrace` message. This opens a trace file and starts capturing all reaction events:
@@ -44,27 +65,6 @@ emit(std::make_unique<NUClear::message::EndTrace>());
 
 This closes the trace file cleanly. If you don't emit `EndTrace`, the file will be closed when the PowerPlant shuts down, but may be incomplete.
 
-## Installing the TraceController
-
-The `TraceController` must be installed before you can start tracing. Add it to your PowerPlant setup:
-
-```cpp
-#include <nuclear>
-
-int main(int argc, const char* argv[]) {
-    NUClear::Configuration config;
-    NUClear::PowerPlant plant(config, argc, argv);
-
-    // Install the trace controller
-    plant.install<NUClear::extension::TraceController>();
-
-    // Install your reactors
-    plant.install<MyApp>();
-
-    plant.start();
-}
-```
-
 ## Viewing the Trace
 
 Once you have a `.trace` file:

docs2/how-to/watchdog-timeouts.md

@@ -36,7 +36,7 @@ Use `on<`[`Watchdog`](../reference/dsl/watchdog.md)`<Group, ticks, period>>()` t
 
 ```cpp
 on<Watchdog<HeartbeatMonitor, 5, std::chrono::seconds>>().then([this] {
-    log<NUClear::WARN>("Heartbeat lost! Attempting recovery...");
+    log<WARN>("Heartbeat lost! Attempting recovery...");
     emit(std::make_unique<RecoveryCommand>());
 });
 ```
@@ -69,7 +69,7 @@ public:
 
         // Fire if no heartbeat for 3 seconds
         on<Watchdog<HeartbeatMonitor, 3, std::chrono::seconds>>().then([this] {
-            log<NUClear::WARN>("Sensor heartbeat lost!");
+            log<WARN>("Sensor heartbeat lost!");
             emit(std::make_unique<RecoveryCommand>());
         });
 
@@ -98,7 +98,7 @@ You can monitor multiple instances of the same group using a runtime argument. E
 ```cpp
 // Monitor each motor independently
 on<Watchdog<MotorMonitor, 500, std::chrono::milliseconds>>(motor_id).then([this] {
-    log<NUClear::WARN>("Motor", motor_id, "stopped responding");
+    log<WARN>("Motor", motor_id, "stopped responding");
 });
 
 // Service a specific motor's watchdog
@@ -144,3 +144,13 @@ Common period types: `std::chrono::milliseconds`, `std::chrono::seconds`, `std::
 - The watchdog starts timing from the moment `bind` is called (when the `on<>` statement runs). Service it early if you need a grace period at startup.
 - If the watchdog fires, the timer resets automatically — it will fire again after another timeout unless serviced.
 - Use specific group types to avoid accidentally servicing the wrong watchdog.
+- If a reactor only needs a single watchdog, you can use the reactor type itself as the group instead of creating a separate tag type:
+    ```cpp
+    class SensorReader : public NUClear::Reactor {
+        // ...
+        on<Watchdog<SensorReader, 5, std::chrono::seconds>>().then([this] {
+            log<WARN>("Sensor timeout!");
+        });
+        // Service with: emit<Scope::WATCHDOG>(ServiceWatchdog<SensorReader>());
+    };
+    ```

docs2/index.md

@@ -28,7 +28,7 @@ public:
 
         on<Trigger<SensorData>>().then([this](const SensorData& data) {
             if (data.temperature > 100.0) {
-                log<NUClear::LogLevel::WARN>("Temperature critical:", data.temperature);
+                log<WARN>("Temperature critical:", data.temperature);
             }
         });
     }

docs2/reference/dsl/always.md

@@ -45,6 +45,9 @@ public:
 !!! warning "CPU Spinning"
     If the callback returns without blocking or sleeping, the reaction will busy-spin and consume 100% CPU on its dedicated thread. Always ensure the callback performs blocking work or includes an explicit sleep/wait.
 
+!!! warning "Don't block forever"
+    The callback must periodically return or yield so that NUClear can shut down the system gracefully. If you block indefinitely (e.g., an infinite wait with no timeout), the PowerPlant cannot stop the thread when shutdown is requested. Use timeouts on blocking calls and check if the system is shutting down regularly.
+
 - Always gets its own thread — it does not consume a thread from the default pool.
 - Good for: polling hardware, running event loops, blocking I/O loops.
 - Bad for: work that could be event-driven. Prefer [Trigger](trigger.md) or [Every](every.md) instead.