diff --git a/pkg/ueps/packet.go b/pkg/ueps/packet.go
index 7c34a52..22b199b 100644
--- a/pkg/ueps/packet.go
+++ b/pkg/ueps/packet.go
@@ -29,13 +29,15 @@ type UEPSHeader struct {
 	ThreatScore  uint16 // 0-65535
 }
 
-// PacketBuilder helps construct a signed UEPS frame
+// builder := ueps.NewBuilder(intentID, payload); frame, _ := builder.MarshalAndSign(secret)
 type PacketBuilder struct {
 	Header  UEPSHeader
 	Payload []byte
 }
 
-// NewBuilder creates a packet context for a specific intent
+// builder := ueps.NewBuilder(0x01, []byte("hello"))
+// builder.Header.ThreatScore = 100
+// frame, err := builder.MarshalAndSign(sharedSecret)
 func NewBuilder(intentID uint8, payload []byte) *PacketBuilder {
 	return &PacketBuilder{
 		Header: UEPSHeader{
@@ -49,7 +51,7 @@ func NewBuilder(intentID uint8, payload []byte) *PacketBuilder {
 	}
 }
 
-// MarshalAndSign generates the final byte stream using the shared secret
+// frame, err := builder.MarshalAndSign([]byte("my-shared-secret"))
 func (p *PacketBuilder) MarshalAndSign(sharedSecret []byte) ([]byte, error) {
 	buf := new(bytes.Buffer)
 
diff --git a/pkg/ueps/reader.go b/pkg/ueps/reader.go
index b0854e4..b37d602 100644
--- a/pkg/ueps/reader.go
+++ b/pkg/ueps/reader.go
@@ -11,14 +11,14 @@ import (
 	"io"
 )
 
-// ParsedPacket holds the verified data
+// packet.Header.ThreatScore, packet.Header.IntentID, packet.Payload
 type ParsedPacket struct {
 	Header  UEPSHeader
 	Payload []byte
 }
 
-// ReadAndVerify reads a UEPS frame from the stream and validates the HMAC.
-// It consumes the stream up to the end of the packet.
+// packet, err := ueps.ReadAndVerify(bufio.NewReader(conn), []byte("my-shared-secret"))
+// if err != nil { /* integrity violation or truncated frame */ }
 func ReadAndVerify(r *bufio.Reader, sharedSecret []byte) (*ParsedPacket, error) {
 	// Buffer to reconstruct the data for HMAC verification
 	// We have to "record" what we read to verify the signature later.