docs(mcp): add usage examples to remaining public DTOs

Align the IDE bridge and brain subsystem public types with the repo's AX-style comment convention by adding concrete usage examples for bridge messages, DTOs, and helper callbacks.

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

pkg/mcp/brain/direct.go

@@ -21,6 +21,8 @@ import (
 )
 
 // channelSender is the callback for pushing channel events.
+//
+//	fn := func(ctx context.Context, channel string, data any) { ... }
 type channelSender func(ctx context.Context, channel string, data any)
 
 // DirectSubsystem implements mcp.Subsystem for OpenBrain via direct HTTP calls.

pkg/mcp/brain/tools.go

@@ -22,6 +22,8 @@ func (s *Subsystem) emitChannel(ctx context.Context, channel string, data any) {
 // -- Input/Output types -------------------------------------------------------
 
 // RememberInput is the input for brain_remember.
+//
+//	input := RememberInput{Content: "Use Qdrant for vector search", Type: "decision"}
 type RememberInput struct {
 	Content    string   `json:"content"`
 	Type       string   `json:"type"`
@@ -33,6 +35,8 @@ type RememberInput struct {
 }
 
 // RememberOutput is the output for brain_remember.
+//
+//	// out.Success == true
 type RememberOutput struct {
 	Success   bool      `json:"success"`
 	MemoryID  string    `json:"memoryId,omitempty"`
@@ -40,6 +44,8 @@ type RememberOutput struct {
 }
 
 // RecallInput is the input for brain_recall.
+//
+//	input := RecallInput{Query: "vector search", TopK: 5}
 type RecallInput struct {
 	Query  string       `json:"query"`
 	TopK   int          `json:"top_k,omitempty"`
@@ -47,6 +53,8 @@ type RecallInput struct {
 }
 
 // RecallFilter holds optional filter criteria for brain_recall.
+//
+//	filter := RecallFilter{Project: "core/mcp", MinConfidence: 0.5}
 type RecallFilter struct {
 	Project       string  `json:"project,omitempty"`
 	Type          any     `json:"type,omitempty"`
@@ -55,6 +63,8 @@ type RecallFilter struct {
 }
 
 // RecallOutput is the output for brain_recall.
+//
+//	// out.Memories contains ranked matches
 type RecallOutput struct {
 	Success  bool     `json:"success"`
 	Count    int      `json:"count"`
@@ -62,6 +72,8 @@ type RecallOutput struct {
 }
 
 // Memory is a single memory entry returned by recall or list.
+//
+//	mem := Memory{ID: "m1", Type: "bug", Content: "Fix timeout handling"}
 type Memory struct {
 	ID           string   `json:"id"`
 	AgentID      string   `json:"agent_id"`
@@ -77,12 +89,16 @@ type Memory struct {
 }
 
 // ForgetInput is the input for brain_forget.
+//
+//	input := ForgetInput{ID: "m1"}
 type ForgetInput struct {
 	ID     string `json:"id"`
 	Reason string `json:"reason,omitempty"`
 }
 
 // ForgetOutput is the output for brain_forget.
+//
+//	// out.Forgotten contains the deleted memory ID
 type ForgetOutput struct {
 	Success   bool      `json:"success"`
 	Forgotten string    `json:"forgotten"`
@@ -90,6 +106,8 @@ type ForgetOutput struct {
 }
 
 // ListInput is the input for brain_list.
+//
+//	input := ListInput{Project: "core/mcp", Limit: 50}
 type ListInput struct {
 	Project string `json:"project,omitempty"`
 	Type    string `json:"type,omitempty"`
@@ -98,6 +116,8 @@ type ListInput struct {
 }
 
 // ListOutput is the output for brain_list.
+//
+//	// out.Count reports how many memories were returned
 type ListOutput struct {
 	Success  bool     `json:"success"`
 	Count    int      `json:"count"`

pkg/mcp/ide/bridge.go

@@ -12,7 +12,13 @@ import (
 	"github.com/gorilla/websocket"
 )
 
-// BridgeMessage is the wire format between the IDE and Laravel.
+// BridgeMessage is the wire format between the IDE bridge and Laravel.
+//
+//	msg := BridgeMessage{
+//	    Type: "chat_send",
+//	    SessionID: "sess-42",
+//	    Data: "hello",
+//	}
 type BridgeMessage struct {
 	Type      string    `json:"type"`
 	Channel   string    `json:"channel,omitempty"`
@@ -23,6 +29,8 @@ type BridgeMessage struct {
 
 // Bridge maintains a WebSocket connection to the Laravel core-agentic
 // backend and forwards responses to a local ws.Hub.
+//
+//	bridge := NewBridge(hub, cfg)
 type Bridge struct {
 	cfg  Config
 	hub  *ws.Hub
@@ -43,6 +51,10 @@ func NewBridge(hub *ws.Hub, cfg Config) *Bridge {
 }
 
 // SetObserver registers a callback for inbound bridge messages.
+//
+//	bridge.SetObserver(func(msg BridgeMessage) {
+//	    fmt.Println(msg.Type)
+//	})
 func (b *Bridge) SetObserver(fn func(BridgeMessage)) {
 	b.mu.Lock()
 	defer b.mu.Unlock()
@@ -55,6 +67,8 @@ func (b *Bridge) SetObserver(fn func(BridgeMessage)) {
 
 // AddObserver registers an additional bridge observer.
 // Observers are invoked in registration order after each inbound message.
+//
+//	bridge.AddObserver(func(msg BridgeMessage) { log.Println(msg.Type) })
 func (b *Bridge) AddObserver(fn func(BridgeMessage)) {
 	if fn == nil {
 		return
@@ -66,12 +80,16 @@ func (b *Bridge) AddObserver(fn func(BridgeMessage)) {
 
 // Start begins the connection loop in a background goroutine.
 // Call Shutdown to stop it.
+//
+//	bridge.Start(ctx)
 func (b *Bridge) Start(ctx context.Context) {
 	ctx, b.cancel = context.WithCancel(ctx)
 	go b.connectLoop(ctx)
 }
 
 // Shutdown cleanly closes the bridge.
+//
+//	bridge.Shutdown()
 func (b *Bridge) Shutdown() {
 	if b.cancel != nil {
 		b.cancel()
@@ -86,6 +104,10 @@ func (b *Bridge) Shutdown() {
 }
 
 // Connected reports whether the bridge has an active connection.
+//
+//	if bridge.Connected() {
+//	    fmt.Println("online")
+//	}
 func (b *Bridge) Connected() bool {
 	b.mu.Lock()
 	defer b.mu.Unlock()
@@ -93,6 +115,8 @@ func (b *Bridge) Connected() bool {
 }
 
 // Send sends a message to the Laravel backend.
+//
+//	err := bridge.Send(BridgeMessage{Type: "dashboard_overview"})
 func (b *Bridge) Send(msg BridgeMessage) error {
 	b.mu.Lock()
 	defer b.mu.Unlock()

pkg/mcp/ide/tools_build.go

@@ -10,11 +10,15 @@ import (
 // Build tool input/output types.
 
 // BuildStatusInput is the input for ide_build_status.
+//
+//	input := BuildStatusInput{BuildID: "build-123"}
 type BuildStatusInput struct {
 	BuildID string `json:"buildId"`
 }
 
 // BuildInfo represents a single build.
+//
+//	info := BuildInfo{ID: "build-123", Repo: "go-io", Status: "running"}
 type BuildInfo struct {
 	ID        string    `json:"id"`
 	Repo      string    `json:"repo"`
@@ -25,28 +29,38 @@ type BuildInfo struct {
 }
 
 // BuildStatusOutput is the output for ide_build_status.
+//
+//	// out.Build.Status == "running"
 type BuildStatusOutput struct {
 	Build BuildInfo `json:"build"`
 }
 
 // BuildListInput is the input for ide_build_list.
+//
+//	input := BuildListInput{Repo: "go-io", Limit: 20}
 type BuildListInput struct {
 	Repo  string `json:"repo,omitempty"`
 	Limit int    `json:"limit,omitempty"`
 }
 
 // BuildListOutput is the output for ide_build_list.
+//
+//	// out.Builds holds the local build snapshot
 type BuildListOutput struct {
 	Builds []BuildInfo `json:"builds"`
 }
 
 // BuildLogsInput is the input for ide_build_logs.
+//
+//	input := BuildLogsInput{BuildID: "build-123", Tail: 200}
 type BuildLogsInput struct {
 	BuildID string `json:"buildId"`
 	Tail    int    `json:"tail,omitempty"`
 }
 
 // BuildLogsOutput is the output for ide_build_logs.
+//
+//	// out.Lines contains the captured build log lines
 type BuildLogsOutput struct {
 	BuildID string   `json:"buildId"`
 	Lines   []string `json:"lines"`

pkg/mcp/ide/tools_chat.go

@@ -11,12 +11,16 @@ import (
 // Chat tool input/output types.
 
 // ChatSendInput is the input for ide_chat_send.
+//
+//	input := ChatSendInput{SessionID: "sess-42", Message: "hello"}
 type ChatSendInput struct {
 	SessionID string `json:"sessionId"`
 	Message   string `json:"message"`
 }
 
 // ChatSendOutput is the output for ide_chat_send.
+//
+//	// out.Sent == true, out.SessionID == "sess-42"
 type ChatSendOutput struct {
 	Sent      bool      `json:"sent"`
 	SessionID string    `json:"sessionId"`
@@ -24,12 +28,16 @@ type ChatSendOutput struct {
 }
 
 // ChatHistoryInput is the input for ide_chat_history.
+//
+//	input := ChatHistoryInput{SessionID: "sess-42", Limit: 50}
 type ChatHistoryInput struct {
 	SessionID string `json:"sessionId"`
 	Limit     int    `json:"limit,omitempty"`
 }
 
 // ChatMessage represents a single message in history.
+//
+//	msg := ChatMessage{Role: "user", Content: "hello"}
 type ChatMessage struct {
 	Role      string    `json:"role"`
 	Content   string    `json:"content"`
@@ -37,15 +45,21 @@ type ChatMessage struct {
 }
 
 // ChatHistoryOutput is the output for ide_chat_history.
+//
+//	// out.Messages contains the stored chat transcript
 type ChatHistoryOutput struct {
 	SessionID string        `json:"sessionId"`
 	Messages  []ChatMessage `json:"messages"`
 }
 
 // SessionListInput is the input for ide_session_list.
+//
+//	input := SessionListInput{}
 type SessionListInput struct{}
 
 // Session represents an agent session.
+//
+//	session := Session{ID: "sess-42", Name: "draft", Status: "running"}
 type Session struct {
 	ID        string    `json:"id"`
 	Name      string    `json:"name"`
@@ -54,32 +68,44 @@ type Session struct {
 }
 
 // SessionListOutput is the output for ide_session_list.
+//
+//	// out.Sessions contains every locally tracked session
 type SessionListOutput struct {
 	Sessions []Session `json:"sessions"`
 }
 
 // SessionCreateInput is the input for ide_session_create.
+//
+//	input := SessionCreateInput{Name: "draft"}
 type SessionCreateInput struct {
 	Name string `json:"name"`
 }
 
 // SessionCreateOutput is the output for ide_session_create.
+//
+//	// out.Session.ID is assigned by the backend or local store
 type SessionCreateOutput struct {
 	Session Session `json:"session"`
 }
 
 // PlanStatusInput is the input for ide_plan_status.
+//
+//	input := PlanStatusInput{SessionID: "sess-42"}
 type PlanStatusInput struct {
 	SessionID string `json:"sessionId"`
 }
 
 // PlanStep is a single step in an agent plan.
+//
+//	step := PlanStep{Name: "prep", Status: "done"}
 type PlanStep struct {
 	Name   string `json:"name"`
 	Status string `json:"status"`
 }
 
 // PlanStatusOutput is the output for ide_plan_status.
+//
+//	// out.Steps contains the current plan breakdown
 type PlanStatusOutput struct {
 	SessionID string     `json:"sessionId"`
 	Status    string     `json:"status"`

pkg/mcp/ide/tools_dashboard.go

@@ -10,9 +10,13 @@ import (
 // Dashboard tool input/output types.
 
 // DashboardOverviewInput is the input for ide_dashboard_overview.
+//
+//	input := DashboardOverviewInput{}
 type DashboardOverviewInput struct{}
 
 // DashboardOverview contains high-level platform stats.
+//
+//	overview := DashboardOverview{Repos: 12, ActiveSessions: 3}
 type DashboardOverview struct {
 	Repos          int  `json:"repos"`
 	Services       int  `json:"services"`
@@ -22,16 +26,22 @@ type DashboardOverview struct {
 }
 
 // DashboardOverviewOutput is the output for ide_dashboard_overview.
+//
+//	// out.Overview.BridgeOnline reports bridge connectivity
 type DashboardOverviewOutput struct {
 	Overview DashboardOverview `json:"overview"`
 }
 
 // DashboardActivityInput is the input for ide_dashboard_activity.
+//
+//	input := DashboardActivityInput{Limit: 25}
 type DashboardActivityInput struct {
 	Limit int `json:"limit,omitempty"`
 }
 
 // ActivityEvent represents a single activity feed item.
+//
+//	event := ActivityEvent{Type: "build", Message: "build finished"}
 type ActivityEvent struct {
 	Type      string    `json:"type"`
 	Message   string    `json:"message"`
@@ -39,16 +49,22 @@ type ActivityEvent struct {
 }
 
 // DashboardActivityOutput is the output for ide_dashboard_activity.
+//
+//	// out.Events contains the recent activity feed
 type DashboardActivityOutput struct {
 	Events []ActivityEvent `json:"events"`
 }
 
 // DashboardMetricsInput is the input for ide_dashboard_metrics.
+//
+//	input := DashboardMetricsInput{Period: "24h"}
 type DashboardMetricsInput struct {
 	Period string `json:"period,omitempty"` // "1h", "24h", "7d"
 }
 
 // DashboardMetrics contains aggregate metrics.
+//
+//	metrics := DashboardMetrics{BuildsTotal: 42, SuccessRate: 0.95}
 type DashboardMetrics struct {
 	BuildsTotal   int     `json:"buildsTotal"`
 	BuildsSuccess int     `json:"buildsSuccess"`
@@ -60,6 +76,8 @@ type DashboardMetrics struct {
 }
 
 // DashboardMetricsOutput is the output for ide_dashboard_metrics.
+//
+//	// out.Metrics summarises the selected time window
 type DashboardMetricsOutput struct {
 	Period  string           `json:"period"`
 	Metrics DashboardMetrics `json:"metrics"`