From 6bc24d521393be2f1b3cb731f2e099726bf5b550 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Thu, 2 Apr 2026 09:07:12 +0000
Subject: [PATCH] docs(ax): replace alias descriptions with usage examples

Co-Authored-By: Virgil <virgil@lethean.io>
---
 pkg/agentic/phase.go   | 2 +-
 pkg/agentic/plan.go    | 2 +-
 pkg/agentic/session.go | 2 +-
 pkg/agentic/state.go   | 2 +-
 pkg/brain/tools.go     | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/pkg/agentic/phase.go b/pkg/agentic/phase.go
index fcf7f44..d3eebc0 100644
--- a/pkg/agentic/phase.go
+++ b/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"}))
diff --git a/pkg/agentic/plan.go b/pkg/agentic/plan.go
index 6c3be07..03784bb 100644
--- a/pkg/agentic/plan.go
+++ b/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"}
diff --git a/pkg/agentic/session.go b/pkg/agentic/session.go
index f76834a..dd882fb 100644
--- a/pkg/agentic/session.go
+++ b/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"}
diff --git a/pkg/agentic/state.go b/pkg/agentic/state.go
index 0347122..79fd749 100644
--- a/pkg/agentic/state.go
+++ b/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"}
diff --git a/pkg/brain/tools.go b/pkg/brain/tools.go
index bef6b14..25d2775 100644
--- a/pkg/brain/tools.go
+++ b/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{