diff --git a/internal/beads/beads.go b/internal/beads/beads.go
index f60c71dc..682930ac 100644
--- a/internal/beads/beads.go
+++ b/internal/beads/beads.go
@@ -518,7 +518,7 @@ type AgentFields struct {
 	Rig        string // Rig name (empty for global agents like mayor/deacon)
 	AgentState string // spawning, working, done, stuck
 	HookBead   string // Currently pinned work bead ID
-	RoleBead   string // Role definition bead ID
+	RoleBead   string // Role definition bead ID (canonical location; may not exist yet)
 }
 
 // FormatAgentDescription creates a description string from agent fields.
diff --git a/internal/rig/manager.go b/internal/rig/manager.go
index b84ad954..20cb4b74 100644
--- a/internal/rig/manager.go
+++ b/internal/rig/manager.go
@@ -445,6 +445,9 @@ func (m *Manager) initAgentBeads(rigPath, rigName, prefix string, isFirstRig boo
 			continue // Already exists
 		}
 
+		// RoleBead establishes the canonical bead ID for this agent's role definition.
+		// The bead may not exist yet - this declares the naming convention so tooling
+		// (like gt doctor) can check for missing role beads and scaffold them.
 		fields := &beads.AgentFields{
 			RoleType:   agent.roleType,
 			Rig:        agent.rig,