docs(ax): replace alias descriptions with usage examples

Co-Authored-By: Virgil <virgil@lethean.io>

pkg/agentic/phase.go

@@ -38,7 +38,7 @@ type PhaseOutput struct {
 	Phase   Phase `json:"phase"`
 }
 
-// AgentPhase is the RFC-named alias for Phase.
+// phase := agentic.AgentPhase{Number: 1, Name: "Build", Status: "in_progress"}
 type AgentPhase = Phase
 
 // result := c.Action("phase.get").Run(ctx, core.NewOptions(core.Option{Key: "plan_slug", Value: "my-plan-abc123"}))

pkg/agentic/plan.go

@@ -38,7 +38,7 @@ type Plan struct {
 	ArchivedAt        time.Time           `json:"archived_at,omitempty"`
 }
 
-// AgentPlan is the RFC-named alias for Plan.
+// plan := agentic.AgentPlan{Slug: "ax-follow-up", Title: "AX follow-up"}
 type AgentPlan = Plan
 
 // phase := agentic.Phase{Number: 1, Name: "Migrate strings", Status: "in_progress"}

pkg/agentic/session.go

@@ -31,7 +31,7 @@ type Session struct {
 	EndedAt        string           `json:"ended_at,omitempty"`
 }
 
-// AgentSession is the RFC-named alias for Session.
+// session := agentic.AgentSession{SessionID: "ses_abc123", AgentType: "codex", Status: "active"}
 type AgentSession = Session
 
 // input := agentic.SessionStartInput{AgentType: "codex", PlanSlug: "ax-follow-up"}

pkg/agentic/state.go

@@ -21,7 +21,7 @@ type WorkspaceState struct {
 	UpdatedAt   string `json:"updated_at,omitempty"`
 }
 
-// PlanState is kept as a compatibility alias for older callers.
+// state := agentic.PlanState{Key: "pattern", Value: "observer", Type: "general"}
 type PlanState = WorkspaceState
 
 // input := agentic.StateSetInput{PlanSlug: "ax-follow-up", Key: "pattern", Value: "observer", Type: "general", Description: "Shared across sessions"}

pkg/brain/tools.go

@@ -89,7 +89,7 @@ type Memory struct {
 	UpdatedAt       string   `json:"updated_at"`
 }
 
-// BrainMemory is the RFC-named alias for Memory.
+// memory := brain.BrainMemory{ID: "mem_123", Type: "convention", Content: "Use core.Trim for clean input."}
 type BrainMemory = Memory
 
 //	input := brain.ForgetInput{