diff --git a/internal/beads/beads.go b/internal/beads/beads.go
index 70f90c1d4f..1dc6d9b081 100644
--- a/internal/beads/beads.go
+++ b/internal/beads/beads.go
@@ -1,4 +1,6 @@
 // Package beads provides a wrapper for the bd (beads) CLI.
+// Use New() to create a Beads instance for a working directory, then call
+// methods like List(), Show(), Create(), Update(), and Close() to manage issues.
 package beads
 
 import (
@@ -117,6 +119,8 @@ type Beads struct {
 }
 
 // New creates a new Beads wrapper for the given directory.
+// This is the main entry point for interacting with the beads CLI programmatically.
+// The workDir should be a directory containing or inheriting a .beads database.
 func New(workDir string) *Beads {
 	return &Beads{workDir: workDir}
 }