From cef4d5d1f6dfdf51f57fa0ca0269d0363b571eaa Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Sun, 29 Mar 2026 23:14:26 +0000
Subject: [PATCH] docs(ax): add remaining usage examples

Co-Authored-By: Virgil <virgil@lethean.io>
---
 pkg/agentic/prep.go      | 21 +++++++++++++++++----
 pkg/agentic/queue.go     |  5 ++++-
 pkg/agentic/runner.go    | 12 +++++++++---
 pkg/agentic/transport.go | 13 +++++++++++++
 pkg/runner/queue.go      |  5 ++++-
 5 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/pkg/agentic/prep.go b/pkg/agentic/prep.go
index 361fb4f..509a65e 100644
--- a/pkg/agentic/prep.go
+++ b/pkg/agentic/prep.go
@@ -212,7 +212,10 @@ func (s *PrepSubsystem) OnStartup(ctx context.Context) core.Result {
 
 // registerCommands is in commands.go
 
-// OnShutdown implements core.Stoppable — freezes the queue.
+// OnShutdown implements core.Stoppable and freezes the queue.
+//
+//	prep := agentic.NewPrep()
+//	_ = prep.OnShutdown(context.Background())
 func (s *PrepSubsystem) OnShutdown(ctx context.Context) core.Result {
 	s.frozen = true
 	return core.Result{OK: true}
@@ -262,10 +265,17 @@ func envOr(key, fallback string) string {
 	return fallback
 }
 
-// Name implements mcp.Subsystem.
+// Name identifies the MCP subsystem.
+//
+//	prep := agentic.NewPrep()
+//	name := prep.Name()
+//	_ = name // "agentic"
 func (s *PrepSubsystem) Name() string { return "agentic" }
 
-// RegisterTools implements mcp.Subsystem.
+// RegisterTools publishes the agentic MCP tools on the server.
+//
+//	prep := agentic.NewPrep()
+//	prep.RegisterTools(server)
 func (s *PrepSubsystem) RegisterTools(server *mcp.Server) {
 	mcp.AddTool(server, &mcp.Tool{
 		Name:        "agentic_prep_workspace",
@@ -293,7 +303,10 @@ func (s *PrepSubsystem) RegisterTools(server *mcp.Server) {
 	s.registerWatchTool(server)
 }
 
-// Shutdown implements mcp.SubsystemWithShutdown.
+// Shutdown satisfies mcp.SubsystemWithShutdown for clean server teardown.
+//
+//	prep := agentic.NewPrep()
+//	_ = prep.Shutdown(context.Background())
 func (s *PrepSubsystem) Shutdown(_ context.Context) error { return nil }
 
 // --- Input/Output types ---
diff --git a/pkg/agentic/queue.go b/pkg/agentic/queue.go
index 5021df0..3a3690e 100644
--- a/pkg/agentic/queue.go
+++ b/pkg/agentic/queue.go
@@ -44,7 +44,10 @@ type ConcurrencyLimit struct {
 	Models map[string]int
 }
 
-// UnmarshalYAML handles both int and map forms.
+// UnmarshalYAML handles both int and map forms for concurrency limits.
+//
+//	var limit ConcurrencyLimit
+//	_ = yaml.Unmarshal([]byte("total: 2\ngpt-5.4: 1\n"), &limit)
 func (c *ConcurrencyLimit) UnmarshalYAML(value *yaml.Node) error {
 	// Try int first
 	var n int
diff --git a/pkg/agentic/runner.go b/pkg/agentic/runner.go
index 78ce141..c534ad6 100644
--- a/pkg/agentic/runner.go
+++ b/pkg/agentic/runner.go
@@ -2,13 +2,19 @@
 
 package agentic
 
-// StartRunner is a no-op — queue drain is now owned by pkg/runner.Service.
-// Kept for backward compatibility with OnStartup call.
+// StartRunner preserves the legacy PrepSubsystem call after queue ownership moved to pkg/runner.Service.
+//
+//	prep := agentic.NewPrep()
+//	prep.StartRunner()
 //
 // The runner service registers as core.WithService(runner.Register) and
 // manages its own background loop, frozen state, and concurrency checks.
 func (s *PrepSubsystem) StartRunner() {}
 
-// Poke is a no-op — queue poke is now owned by pkg/runner.Service.
+// Poke preserves the legacy queue signal after queue ownership moved to pkg/runner.Service.
+//
+//	prep := agentic.NewPrep()
+//	prep.Poke()
+//
 // Runner catches AgentCompleted via HandleIPCEvents and pokes itself.
 func (s *PrepSubsystem) Poke() {}
diff --git a/pkg/agentic/transport.go b/pkg/agentic/transport.go
index cf2c81e..19f8993 100644
--- a/pkg/agentic/transport.go
+++ b/pkg/agentic/transport.go
@@ -26,6 +26,10 @@ type httpStream struct {
 	response []byte
 }
 
+// Send issues the configured HTTP request and caches the response body for Receive.
+//
+//	stream := &httpStream{client: defaultClient, url: "https://forge.lthn.ai/api/v1/version", method: "GET"}
+//	_ = stream.Send(nil)
 func (s *httpStream) Send(data []byte) error {
 	req, err := http.NewRequestWithContext(context.Background(), s.method, s.url, core.NewReader(string(data)))
 	if err != nil {
@@ -50,10 +54,19 @@ func (s *httpStream) Send(data []byte) error {
 	return nil
 }
 
+// Receive returns the cached response body from the last Send call.
+//
+//	stream := &httpStream{response: []byte(`{"ok":true}`)}
+//	data, _ := stream.Receive()
+//	_ = data
 func (s *httpStream) Receive() ([]byte, error) {
 	return s.response, nil
 }
 
+// Close satisfies core.Stream for one-shot HTTP requests.
+//
+//	stream := &httpStream{}
+//	_ = stream.Close()
 func (s *httpStream) Close() error {
 	return nil
 }
diff --git a/pkg/runner/queue.go b/pkg/runner/queue.go
index 2e032ad..f6241e3 100644
--- a/pkg/runner/queue.go
+++ b/pkg/runner/queue.go
@@ -44,7 +44,10 @@ type ConcurrencyLimit struct {
 	Models map[string]int
 }
 
-// UnmarshalYAML handles both int and map forms.
+// UnmarshalYAML handles both int and map forms for concurrency limits.
+//
+//	var limit ConcurrencyLimit
+//	_ = yaml.Unmarshal([]byte("total: 5\ngpt-5.4: 1\n"), &limit)
 func (c *ConcurrencyLimit) UnmarshalYAML(value *yaml.Node) error {
 	var n int
 	if err := value.Decode(&n); err == nil {