fix(ax): align comments with usage examples

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

cmd/core-agent/main.go

@@ -22,11 +22,9 @@ func main() {
 	}
 }
 
-// newCoreAgent builds the Core app with services and CLI commands wired for startup.
-//
-//	c := newCoreAgent()
-//	core.Println(c.App().Name)    // "core-agent"
-//	core.Println(c.App().Version) // "dev" or linked version
+// app := newCoreAgent()
+// core.Println(app.App().Name)    // "core-agent"
+// core.Println(app.App().Version) // "dev" or linked version
 func newCoreAgent() *core.Core {
 	coreApp := core.New(
 		core.WithOption("name", "core-agent"),
@@ -48,10 +46,8 @@ func newCoreAgent() *core.Core {
 	return coreApp
 }
 
-// applicationVersion resolves the build version injected at link time.
-//
-//	agentpkg.Version = "0.15.0"
-//	applicationVersion() // "0.15.0"
+// agentpkg.Version = "0.15.0"
+// applicationVersion() // "0.15.0"
 func applicationVersion() string {
 	if agentpkg.Version != "" {
 		return agentpkg.Version
@@ -59,16 +55,15 @@ func applicationVersion() string {
 	return "dev"
 }
 
-// runCoreAgent builds the runtime and executes the CLI with startup flags applied.
-//
-//	err := runCoreAgent()
+//	if err := runCoreAgent(); err != nil {
+//		core.Error("core-agent failed", "err", err)
+//	}
 func runCoreAgent() error {
 	return runApp(newCoreAgent(), startupArgs())
 }
 
-// runApp starts services, runs the CLI with explicit args, then shuts down.
-//
-//	err := runApp(c, []string{"version"})
+// app := newCoreAgent()
+// _ = runApp(app, []string{"version"})
 func runApp(coreApp *core.Core, cliArgs []string) error {
 	if coreApp == nil {
 		return core.E("main.runApp", "core is required", nil)
@@ -91,9 +86,8 @@ func runApp(coreApp *core.Core, cliArgs []string) error {
 	return nil
 }
 
-// resultError extracts the error from a Result or wraps the failure in core.E().
-//
-//	err := resultError("main.runApp", "startup failed", result)
+// result := core.Result{OK: false, Value: core.E("main.runApp", "startup failed", nil)}
+// err := resultError("main.runApp", "startup failed", result)
 func resultError(op, msg string, result core.Result) error {
 	if result.OK {
 		return nil

pkg/agentic/commands.go

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 
-// CLI commands registered by the agentic service during OnStartup.
+// c := core.New(core.WithOption("name", "core-agent"))
+// registerApplicationCommands(c)
 
 package agentic
 
@@ -24,10 +25,8 @@ func (s *PrepSubsystem) registerCommands(ctx context.Context) {
 	c.Command("extract", core.Command{Description: "Extract a workspace template to a directory", Action: s.cmdExtract})
 }
 
-// commandContext returns the startup context captured during command registration.
-//
-//	ctx := s.commandContext()
-//	_ = ctx.Err()
+// ctx := s.commandContext()
+// _ = ctx.Err()
 func (s *PrepSubsystem) commandContext() context.Context {
 	if s.startupContext != nil {
 		return s.startupContext
@@ -247,7 +246,7 @@ func (s *PrepSubsystem) cmdExtract(options core.Options) core.Result {
 	return core.Result{OK: true}
 }
 
-// parseIntStr extracts digits from a string and returns the integer value.
+// parseIntStr("issue-42") // 42
 func parseIntStr(s string) int {
 	n := 0
 	for _, ch := range s {

pkg/agentic/plan.go

@@ -388,9 +388,7 @@ func readPlanResult(dir, id string) core.Result {
 	return core.Result{Value: &plan, OK: true}
 }
 
-// readPlan reads a plan file. Kept as compatibility wrapper.
-//
-//	plan, err := readPlan(PlansRoot(), "plan-id")
+// plan, err := readPlan(PlansRoot(), "plan-id")
 func readPlan(dir, id string) (*Plan, error) {
 	r := readPlanResult(dir, id)
 	if !r.OK {
@@ -435,9 +433,7 @@ func writePlanResult(dir string, plan *Plan) core.Result {
 	return core.Result{Value: path, OK: true}
 }
 
-// writePlan writes a plan file. Kept as compatibility wrapper.
-//
-//	_, err := writePlan(PlansRoot(), plan)
+// path, err := writePlan(PlansRoot(), plan)
 func writePlan(dir string, plan *Plan) (string, error) {
 	r := writePlanResult(dir, plan)
 	if !r.OK {

pkg/agentic/status.go

@@ -10,19 +10,9 @@ import (
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
-// Workspace status file convention:
-//
-//   {workspace}/status.json  — current state of the workspace
-//   {workspace}/repo/BLOCKED.md   — question the agent needs answered (written by agent)
-//   {workspace}/repo/ANSWER.md    — response from human (written by reviewer)
-//   {workspace}/.meta/agent-*.log — captured agent output
-//
-// Status lifecycle:
-//   running → completed     (normal finish)
-//   running → blocked       (agent wrote BLOCKED.md and exited)
-//   blocked → running       (resume after ANSWER.md provided)
-//   completed → merged      (PR verified and auto-merged)
-//   running → failed        (agent crashed / non-zero exit)
+// statusPath := agentic.WorkspaceStatusPath("/srv/.core/workspace/core/go-io/task-5")
+// blockedPath := agentic.WorkspaceBlockedPath("/srv/.core/workspace/core/go-io/task-5")
+// logs := agentic.WorkspaceLogFiles("/srv/.core/workspace/core/go-io/task-5")
 
 // WorkspaceStatus represents the current state of an agent workspace.
 //

pkg/lib/lib.go

@@ -56,12 +56,9 @@ var (
 	mountResult core.Result
 )
 
-// MountData registers all embedded content (prompts, tasks, flows, personas, workspaces)
-// into Core's Data registry. Other services can then access content without importing lib:
-//
-//	lib.MountData(c)
-//	r := c.Data().ReadString("prompts/coding.md")
-//	r := c.Data().ListNames("flows")
+// lib.MountData(c)
+// r := c.Data().ReadString("prompts/coding.md")
+// r := c.Data().ListNames("flows")
 func MountData(c *core.Core) {
 	if result := ensureMounted(); !result.OK {
 		return

pkg/runner/paths.go

@@ -50,24 +50,20 @@ func agenticWorkspaceStatusFromRunner(status *WorkspaceStatus) *agentic.Workspac
 	}
 }
 
-// WorkspaceRoot returns the root directory for agent workspaces.
-//
-//	root := runner.WorkspaceRoot() // ~/Code/.core/workspace
+// root := runner.WorkspaceRoot()
+// core.Println(root) // "~/Code/.core/workspace"
 func WorkspaceRoot() string {
 	return agentic.WorkspaceRoot()
 }
 
-// CoreRoot returns the root directory for core ecosystem files.
-//
-//	root := runner.CoreRoot() // ~/Code/.core
+// root := runner.CoreRoot()
+// core.Println(root) // "~/Code/.core"
 func CoreRoot() string {
 	return agentic.CoreRoot()
 }
 
-// ReadStatusResult reads status.json as core.Result.
-//
-//	result := ReadStatusResult("/srv/core/workspace/core/go-io/task-5")
-//	if result.OK { workspaceStatus := result.Value.(*WorkspaceStatus) }
+// result := ReadStatusResult("/srv/core/workspace/core/go-io/task-5")
+// if result.OK { workspaceStatus := result.Value.(*WorkspaceStatus) }
 func ReadStatusResult(workspaceDir string) core.Result {
 	statusResult := agentic.ReadStatusResult(workspaceDir)
 	if !statusResult.OK {
@@ -89,10 +85,8 @@ func ReadStatusResult(workspaceDir string) core.Result {
 	return core.Result{Value: workspaceStatus, OK: true}
 }
 
-// WriteStatus writes `status.json` for one workspace directory.
-//
-//	result := runner.WriteStatus("/srv/core/workspace/core/go-io/task-5", &runner.WorkspaceStatus{Status: "running", Agent: "codex"})
-//	core.Println(result.OK)
+// result := runner.WriteStatus("/srv/core/workspace/core/go-io/task-5", &runner.WorkspaceStatus{Status: "running", Agent: "codex"})
+// core.Println(result.OK)
 func WriteStatus(workspaceDir string, status *WorkspaceStatus) core.Result {
 	if status == nil {
 		return core.Result{Value: core.E("runner.WriteStatus", "status is required", nil), OK: false}

pkg/setup/setup.go

@@ -65,7 +65,7 @@ func (s *Service) Run(options Options) core.Result {
 	return core.Result{Value: options.Path, OK: true}
 }
 
-// setupCoreDir creates .core/ with build.yaml and test.yaml.
+// result := setupCoreDir(Options{Path: ".", Force: true}, TypeGo)
 func setupCoreDir(options Options, projectType ProjectType) core.Result {
 	coreDir := core.JoinPath(options.Path, ".core")
 
@@ -111,7 +111,7 @@ func setupCoreDir(options Options, projectType ProjectType) core.Result {
 	return core.Result{Value: coreDir, OK: true}
 }
 
-// scaffoldTemplate extracts a dir template into the target path.
+// result := s.scaffoldTemplate(Options{Path: ".", Template: "default"}, TypeGo, "default")
 func (s *Service) scaffoldTemplate(options Options, projectType ProjectType, templateName string) core.Result {
 	core.Print(nil, "Template: %s", templateName)