docs: add assert documentation

README.md

@@ -77,6 +77,8 @@ Toggle features by setting these variables to ``ON`` or ``OFF`` in your CMake co
 ### 1. Logging
 The Log module uses a Sink architecture. You create a Logger, attach an ILogSink, and log messages using std::format syntax.
 
+
+#### Example
 ```C++
 #include <seallib/log.h>
 #include <iostream>
@@ -104,11 +106,54 @@ int main() {
 ```
 
 ### 2. Assert
-(Documentation pending implementation)
+The assert module provides diagnostic macros made to trap critical logic failures.
 
+#### Macros and their behavior
+| Macro | Debug Mode (`_DEBUG`) | Release Mode |
+| :--- | :--- | :--- |
+| `ASSERT(cond, msg)` | Evaluates `cond`. If `false`, logs the error location, pops up an interactive modal error box, drops a debugger breakpoint trap, and calls `std::exit`. | Evaluates to a compiler optimization hint informing the optimizer that `cond` is always `true`. |
+| `PANIC(msg)` | Logs the error, displays an interactive modal error box, breaks execution, and terminates. | Logs the error, displays an interactive modal error box, breaks execution, and terminates. **Always halts execution.** |
+#### Example
+```c++
+#include <seallib/assert.h>
+
+void processSystemData(void* dataPtr, int size) {
+    // 1. Defensively check states that should literally be impossible in a valid run
+    ASSERT(dataPtr != nullptr, "Managed data pointer cannot be null during processing pipe");
+    
+    // 2. Asserts behave as optimizer hints in Release mode. 
+    // The compiler now optimizes this function knowing 'size' can never be less than zero.
+    ASSERT(size >= 0, "Buffer stream size constraint violation");
+
+    if (size == 0) {
+        return; // Valid empty state
+    }
+
+    // Processing logic...
+}
+
+void processNetworkPacket(int packetId) {
+    switch (packetId) {
+        case 1: /* Handle read */ break;
+        case 2: /* Handle write */ break;
+        default:
+            // 3. Use PANIC for unrecoverable structural states that must crash 
+            // the software immediately in both Debug and Release builds.
+            PANIC("Critical Error: Received completely unhandled or corrupted packet opcode");
+            break;
+    }
+}
+
+int main() {
+    // Fails in debug: triggers a modal error window detailing the file and line number
+    processSystemData(nullptr, -1); 
+
+    return 0;
+}
+```
 ### 3. Events
 The Events module provides a thread and type safe signal/slot mechanism. It allows you to define custom events with any number of parameters and subscribe to them using callbacks.
-#### Basic Usage
+#### Example
 ```cpp
 #include <seallib/event.h>
 #include <iostream>
@@ -146,6 +191,8 @@ The VFS (Virtual File System) module provides a unified interface for file opera
 
 #### Implementing a file provider
 To create a new storage backend (e.g., a zip loader, encrypted volume, etc), you must inherit from `IFileProvider`.
+
+#### Example provider implementation
 ```cpp
 #include <seallib/vfs.h>
 
@@ -196,7 +243,7 @@ public:
 };
 ```
 
-#### Example usage
+#### Example provider usage
 ```c++
 #include <seallib/vfs.h>