diff --git a/crates/punktfunk-core/src/quic/endpoint.rs b/crates/punktfunk-core/src/quic/endpoint.rs
index 652e3a0e..b99ca4c8 100644
--- a/crates/punktfunk-core/src/quic/endpoint.rs
+++ b/crates/punktfunk-core/src/quic/endpoint.rs
@@ -1,3 +1,5 @@
+//! Shared QUIC endpoint construction (host + client) and transport tuning — keep-alive and idle
+//! timeout, certificate-fingerprint helpers, and the TOFU cert-pinning verifier (`PinVerify`).
 use std::sync::{Arc, Mutex};
 
 /// Shared QUIC transport tuning for BOTH the host and client endpoints. Keep-alive is the
diff --git a/crates/punktfunk-core/src/quic/io.rs b/crates/punktfunk-core/src/quic/io.rs
index 2851ecd0..be49aefe 100644
--- a/crates/punktfunk-core/src/quic/io.rs
+++ b/crates/punktfunk-core/src/quic/io.rs
@@ -1,3 +1,5 @@
+//! Length-prefixed framing for QUIC control-stream messages: a `u16` length header followed by the
+//! payload, bounded at 64 KiB (control messages are tiny).
 /// Read one framed message (bounded at 64 KiB — control messages are tiny).
 pub async fn read_msg(recv: &mut quinn::RecvStream) -> std::io::Result<Vec<u8>> {
     let mut len = [0u8; 2];
diff --git a/crates/punktfunk-core/src/quic/pake.rs b/crates/punktfunk-core/src/quic/pake.rs
index 4ad10dba..1b64489a 100644
--- a/crates/punktfunk-core/src/quic/pake.rs
+++ b/crates/punktfunk-core/src/quic/pake.rs
@@ -1,3 +1,5 @@
+//! SPAKE2 password-authenticated key exchange for pairing: derive a shared key from the PIN and
+//! confirm it against both certificate fingerprints.
 use crate::error::{PunktfunkError, Result};
 use hmac::{Hmac, Mac};
 use spake2::{Ed25519Group, Identity, Password, Spake2};