Document preamble setup order

README.md

@@ -14,6 +14,7 @@ reduce this boilerplate through layered abstractions:
 - **Transport adapter** built on Tokio I/O
 - **Framing layer** for length‑prefixed or custom frames
 - **Connection preamble** with customizable validation callbacks [[docs](docs/preamble-validator.md)]
+- Call `with_preamble::<T>()` before registering success or failure callbacks
 - **Serialization engine** using `bincode` or a `wire-rs` wrapper
 - **Routing engine** that dispatches messages by ID
 - **Handler invocation** with extractor support

docs/preamble-validator.md

@@ -31,3 +31,12 @@ sequenceDiagram
 In the tests, a `HotlinePreamble` struct illustrates the pattern, but any
 preamble type may be used. Register callbacks via `on_preamble_decode_success`
 and `on_preamble_decode_failure` on `WireframeServer`.
+
+## Call Order
+
+`WireframeServer::with_preamble::<T>()` must be called **before**
+registering callbacks with `on_preamble_decode_success` or
+`on_preamble_decode_failure`. The method converts the server to use a
+custom preamble type, dropping any callbacks configured on the default
+`()` preamble. Registering callbacks after calling `with_preamble::<T>()`
+ensures they are retained.

src/server.rs

@@ -86,10 +86,23 @@ where
         }
     }
 
-    /// Convert this server to parse a custom preamble `T`.
+    /// Converts the server to use a custom preamble type for incoming connections.
     ///
-    /// Call this before registering preamble handlers, otherwise any
-    /// previously configured callbacks will be dropped.
+    /// Calling this method will drop any previously configured preamble decode callbacks. Use it before registering preamble handlers if you wish to retain them.
+    ///
+    /// # Type Parameters
+    ///
+    /// * `T` – The type to decode as the connection preamble; must implement `bincode::Decode<()>`, `Send`, and `'static`.
+    ///
+    /// # Returns
+    ///
+    /// A new `WireframeServer` instance configured to decode preambles of type `T`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let server = WireframeServer::new(factory).with_preamble::<MyPreamble>();
+    /// ```
     #[must_use]
     pub fn with_preamble<T>(self) -> WireframeServer<F, T>
     where