chore: polish AX v0.8.0 compliance

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

agentci/clotho.go

@@ -2,26 +2,31 @@ package agentci
 
 import (
 	"context"
-	"strings"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 
 	"dappco.re/go/core/scm/jobrunner"
 )
 
 // RunMode determines the execution strategy for a dispatched task.
+// Usage example: var value RunMode
 type RunMode string
 
 const (
+	// Usage example: _ = ModeStandard
 	ModeStandard RunMode = "standard"
-	ModeDual     RunMode = "dual" // The Clotho Protocol — dual-run verification
+	// Usage example: _ = ModeDual
+	ModeDual RunMode = "dual" // The Clotho Protocol — dual-run verification
 )
 
 // Spinner is the Clotho orchestrator that determines the fate of each task.
+// Usage example: var value Spinner
 type Spinner struct {
 	Config ClothoConfig
 	Agents map[string]AgentConfig
 }
 
 // NewSpinner creates a new Clotho orchestrator.
+// Usage example: NewSpinner(...)
 func NewSpinner(cfg ClothoConfig, agents map[string]AgentConfig) *Spinner {
 	return &Spinner{
 		Config: cfg,

agentci/config.go

@@ -2,13 +2,14 @@
 package agentci
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/config"
 	coreerr "dappco.re/go/core/log"
+	"forge.lthn.ai/core/config"
 )
 
 // AgentConfig represents a single agent machine in the config file.
+// Usage example: var value AgentConfig
 type AgentConfig struct {
 	Host          string   `yaml:"host" mapstructure:"host"`
 	QueueDir      string   `yaml:"queue_dir" mapstructure:"queue_dir"`
@@ -23,6 +24,7 @@ type AgentConfig struct {
 }
 
 // ClothoConfig controls the orchestration strategy.
+// Usage example: var value ClothoConfig
 type ClothoConfig struct {
 	Strategy            string  `yaml:"strategy" mapstructure:"strategy"`                         // direct, clotho-verified
 	ValidationThreshold float64 `yaml:"validation_threshold" mapstructure:"validation_threshold"` // divergence limit (0.0-1.0)
@@ -31,6 +33,7 @@ type ClothoConfig struct {
 
 // LoadAgents reads agent targets from config and returns a map of AgentConfig.
 // Returns an empty map (not an error) if no agents are configured.
+// Usage example: LoadAgents(...)
 func LoadAgents(cfg *config.Config) (map[string]AgentConfig, error) {
 	var agents map[string]AgentConfig
 	if err := cfg.Get("agentci.agents", &agents); err != nil {
@@ -61,6 +64,7 @@ func LoadAgents(cfg *config.Config) (map[string]AgentConfig, error) {
 }
 
 // LoadActiveAgents returns only active agents.
+// Usage example: LoadActiveAgents(...)
 func LoadActiveAgents(cfg *config.Config) (map[string]AgentConfig, error) {
 	all, err := LoadAgents(cfg)
 	if err != nil {
@@ -77,6 +81,7 @@ func LoadActiveAgents(cfg *config.Config) (map[string]AgentConfig, error) {
 
 // LoadClothoConfig loads the Clotho orchestrator settings.
 // Returns sensible defaults if no config is present.
+// Usage example: LoadClothoConfig(...)
 func LoadClothoConfig(cfg *config.Config) (ClothoConfig, error) {
 	var cc ClothoConfig
 	if err := cfg.Get("agentci.clotho", &cc); err != nil {
@@ -95,6 +100,7 @@ func LoadClothoConfig(cfg *config.Config) (ClothoConfig, error) {
 }
 
 // SaveAgent writes an agent config entry to the config file.
+// Usage example: SaveAgent(...)
 func SaveAgent(cfg *config.Config, name string, ac AgentConfig) error {
 	key := fmt.Sprintf("agentci.agents.%s", name)
 	data := map[string]any{
@@ -123,6 +129,7 @@ func SaveAgent(cfg *config.Config, name string, ac AgentConfig) error {
 }
 
 // RemoveAgent removes an agent from the config file.
+// Usage example: RemoveAgent(...)
 func RemoveAgent(cfg *config.Config, name string) error {
 	var agents map[string]AgentConfig
 	if err := cfg.Get("agentci.agents", &agents); err != nil {
@@ -136,6 +143,7 @@ func RemoveAgent(cfg *config.Config, name string) error {
 }
 
 // ListAgents returns all configured agents (active and inactive).
+// Usage example: ListAgents(...)
 func ListAgents(cfg *config.Config) (map[string]AgentConfig, error) {
 	var agents map[string]AgentConfig
 	if err := cfg.Get("agentci.agents", &agents); err != nil {

agentci/config_test.go

@@ -3,8 +3,8 @@ package agentci
 import (
 	"testing"
 
-	"forge.lthn.ai/core/config"
 	"dappco.re/go/core/io"
+	"forge.lthn.ai/core/config"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -299,7 +299,7 @@ func TestListAgents_Good_Empty(t *testing.T) {
 	assert.Empty(t, agents)
 }
 
-func TestRoundTrip_SaveThenLoad(t *testing.T) {
+func TestRoundTrip_Good_SaveThenLoad(t *testing.T) {
 	cfg := newTestConfig(t, "")
 
 	err := SaveAgent(cfg, "alpha", AgentConfig{

agentci/security.go

@@ -1,36 +1,148 @@
 package agentci
 
 import (
-	"os/exec"
-	"path/filepath"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
+	exec "golang.org/x/sys/execabs"
+	"path"
 	"regexp"
-	"strings"
 
 	coreerr "dappco.re/go/core/log"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
 )
 
 var safeNameRegex = regexp.MustCompile(`^[a-zA-Z0-9\-\_\.]+$`)
 
 // SanitizePath ensures a filename or directory name is safe and prevents path traversal.
-// Returns filepath.Base of the input after validation.
+// Returns the validated input unchanged.
+// Usage example: SanitizePath(...)
 func SanitizePath(input string) (string, error) {
-	base := filepath.Base(input)
-	if !safeNameRegex.MatchString(base) {
+	if input == "" {
+		return "", coreerr.E("agentci.SanitizePath", "path element is required", nil)
+	}
+	if strings.ContainsAny(input, `/\`) {
+		return "", coreerr.E("agentci.SanitizePath", "path separators are not allowed: "+input, nil)
+	}
+	if input == "." || input == ".." {
+		return "", coreerr.E("agentci.SanitizePath", "invalid path element: "+input, nil)
+	}
+	if !safeNameRegex.MatchString(input) {
 		return "", coreerr.E("agentci.SanitizePath", "invalid characters in path element: "+input, nil)
 	}
-	if base == "." || base == ".." || base == "/" {
-		return "", coreerr.E("agentci.SanitizePath", "invalid path element: "+base, nil)
+	return input, nil
+}
+
+// ValidatePathElement validates a single local path element and returns its safe form.
+// Usage example: ValidatePathElement(...)
+func ValidatePathElement(input string) (string, error) {
+	return SanitizePath(input)
+}
+
+// ResolvePathWithinRoot resolves a validated path element beneath a root directory.
+// Usage example: ResolvePathWithinRoot(...)
+func ResolvePathWithinRoot(root string, input string) (string, string, error) {
+	safeName, err := ValidatePathElement(input)
+	if err != nil {
+		return "", "", coreerr.E("agentci.ResolvePathWithinRoot", "invalid path element", err)
 	}
-	return base, nil
+
+	absRoot, err := filepath.Abs(root)
+	if err != nil {
+		return "", "", coreerr.E("agentci.ResolvePathWithinRoot", "resolve root", err)
+	}
+
+	resolved := filepath.Clean(filepath.Join(absRoot, safeName))
+	cleanRoot := filepath.Clean(absRoot)
+	rootPrefix := cleanRoot + string(filepath.Separator)
+	if resolved != cleanRoot && !strings.HasPrefix(resolved, rootPrefix) {
+		return "", "", coreerr.E("agentci.ResolvePathWithinRoot", "resolved path escaped root", nil)
+	}
+
+	return safeName, resolved, nil
+}
+
+// ValidateRemoteDir validates a remote directory path used over SSH.
+// Usage example: ValidateRemoteDir(...)
+func ValidateRemoteDir(dir string) (string, error) {
+	if strings.TrimSpace(dir) == "" {
+		return "", coreerr.E("agentci.ValidateRemoteDir", "directory is required", nil)
+	}
+	if strings.ContainsAny(dir, `\`) {
+		return "", coreerr.E("agentci.ValidateRemoteDir", "backslashes are not allowed", nil)
+	}
+
+	switch dir {
+	case "/", "~":
+		return dir, nil
+	}
+
+	cleaned := path.Clean(dir)
+	prefix := ""
+	rest := cleaned
+
+	if strings.HasPrefix(dir, "~/") {
+		prefix = "~/"
+		rest = strings.TrimPrefix(cleaned, "~/")
+	}
+	if strings.HasPrefix(dir, "/") {
+		prefix = "/"
+		rest = strings.TrimPrefix(cleaned, "/")
+	}
+
+	if rest == "." || rest == ".." || strings.HasPrefix(rest, "../") {
+		return "", coreerr.E("agentci.ValidateRemoteDir", "directory escaped root", nil)
+	}
+
+	for _, part := range strings.Split(rest, "/") {
+		if part == "" {
+			continue
+		}
+		if _, err := ValidatePathElement(part); err != nil {
+			return "", coreerr.E("agentci.ValidateRemoteDir", "invalid directory segment", err)
+		}
+	}
+
+	if rest == "" || rest == "." {
+		return prefix, nil
+	}
+
+	return prefix + rest, nil
+}
+
+// JoinRemotePath joins validated remote path elements using forward slashes.
+// Usage example: JoinRemotePath(...)
+func JoinRemotePath(base string, parts ...string) (string, error) {
+	safeBase, err := ValidateRemoteDir(base)
+	if err != nil {
+		return "", coreerr.E("agentci.JoinRemotePath", "invalid base directory", err)
+	}
+
+	cleanParts := make([]string, 0, len(parts))
+	for _, part := range parts {
+		safePart, partErr := ValidatePathElement(part)
+		if partErr != nil {
+			return "", coreerr.E("agentci.JoinRemotePath", "invalid path element", partErr)
+		}
+		cleanParts = append(cleanParts, safePart)
+	}
+
+	if safeBase == "~" {
+		return path.Join("~", path.Join(cleanParts...)), nil
+	}
+	if strings.HasPrefix(safeBase, "~/") {
+		return "~/" + path.Join(strings.TrimPrefix(safeBase, "~/"), path.Join(cleanParts...)), nil
+	}
+	return path.Join(append([]string{safeBase}, cleanParts...)...), nil
 }
 
 // EscapeShellArg wraps a string in single quotes for safe remote shell insertion.
 // Prefer exec.Command arguments over constructing shell strings where possible.
+// Usage example: EscapeShellArg(...)
 func EscapeShellArg(arg string) string {
 	return "'" + strings.ReplaceAll(arg, "'", "'\\''") + "'"
 }
 
 // SecureSSHCommand creates an SSH exec.Cmd with strict host key checking and batch mode.
+// Usage example: SecureSSHCommand(...)
 func SecureSSHCommand(host string, remoteCmd string) *exec.Cmd {
 	return exec.Command("ssh",
 		"-o", "StrictHostKeyChecking=yes",
@@ -42,6 +154,7 @@ func SecureSSHCommand(host string, remoteCmd string) *exec.Cmd {
 }
 
 // MaskToken returns a masked version of a token for safe logging.
+// Usage example: MaskToken(...)
 func MaskToken(token string) string {
 	if len(token) < 8 {
 		return "*****"

agentci/security_test.go

@@ -20,7 +20,6 @@ func TestSanitizePath_Good(t *testing.T) {
 		{"with.dot", "with.dot"},
 		{"CamelCase", "CamelCase"},
 		{"123", "123"},
-		{"path/to/file.txt", "file.txt"},
 	}
 
 	for _, tt := range tests {
@@ -44,8 +43,11 @@ func TestSanitizePath_Bad(t *testing.T) {
 		{"pipe", "file|name"},
 		{"ampersand", "file&name"},
 		{"dollar", "file$name"},
+		{"slash", "path/to/file.txt"},
+		{"backslash", `path\to\file.txt`},
 		{"parent traversal base", ".."},
 		{"root", "/"},
+		{"empty", ""},
 	}
 
 	for _, tt := range tests {

cmd/collect/cmd.go

@@ -1,12 +1,12 @@
 package collect
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
-	"dappco.re/go/core/scm/collect"
 	"dappco.re/go/core/i18n"
 	"dappco.re/go/core/io"
+	"dappco.re/go/core/scm/collect"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 func init() {
@@ -28,6 +28,7 @@ var (
 )
 
 // AddCollectCommands registers the 'collect' command and all subcommands.
+// Usage example: AddCollectCommands(...)
 func AddCollectCommands(root *cli.Command) {
 	collectCmd := &cli.Command{
 		Use:   "collect",

cmd/collect/cmd_bitcointalk.go

@@ -2,11 +2,11 @@ package collect
 
 import (
 	"context"
-	"strings"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
-	"dappco.re/go/core/scm/collect"
 	"dappco.re/go/core/i18n"
+	"dappco.re/go/core/scm/collect"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // BitcoinTalk command flags

cmd/collect/cmd_dispatch.go

@@ -1,12 +1,12 @@
 package collect
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 	"time"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
-	collectpkg "dappco.re/go/core/scm/collect"
 	"dappco.re/go/core/i18n"
+	collectpkg "dappco.re/go/core/scm/collect"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // addDispatchCommand adds the 'dispatch' subcommand to the collect parent.

cmd/collect/cmd_excavate.go

@@ -2,11 +2,11 @@ package collect
 
 import (
 	"context"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
-	"dappco.re/go/core/scm/collect"
 	"dappco.re/go/core/i18n"
+	"dappco.re/go/core/scm/collect"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Excavate command flags

cmd/collect/cmd_github.go

@@ -2,11 +2,11 @@ package collect
 
 import (
 	"context"
-	"strings"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
-	"dappco.re/go/core/scm/collect"
 	"dappco.re/go/core/i18n"
+	"dappco.re/go/core/scm/collect"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // GitHub command flags

cmd/collect/cmd_market.go

@@ -3,9 +3,9 @@ package collect
 import (
 	"context"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
-	"dappco.re/go/core/scm/collect"
 	"dappco.re/go/core/i18n"
+	"dappco.re/go/core/scm/collect"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Market command flags

cmd/collect/cmd_papers.go

@@ -3,9 +3,9 @@ package collect
 import (
 	"context"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
-	"dappco.re/go/core/scm/collect"
 	"dappco.re/go/core/i18n"
+	"dappco.re/go/core/scm/collect"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Papers command flags

cmd/collect/cmd_process.go

@@ -3,9 +3,9 @@ package collect
 import (
 	"context"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
-	"dappco.re/go/core/scm/collect"
 	"dappco.re/go/core/i18n"
+	"dappco.re/go/core/scm/collect"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // addProcessCommand adds the 'process' subcommand to the collect parent.

cmd/forge/cmd_auth.go

@@ -1,10 +1,10 @@
 package forge
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	fg "dappco.re/go/core/scm/forge"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Auth command flags.

cmd/forge/cmd_config.go

@@ -1,10 +1,10 @@
 package forge
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	fg "dappco.re/go/core/scm/forge"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Config command flags.

cmd/forge/cmd_forge.go

@@ -33,6 +33,7 @@ var (
 )
 
 // AddForgeCommands registers the 'forge' command and all subcommands.
+// Usage example: AddForgeCommands(...)
 func AddForgeCommands(root *cli.Command) {
 	forgeCmd := &cli.Command{
 		Use:   "forge",

cmd/forge/cmd_issues.go

@@ -1,13 +1,13 @@
 package forge
 
 import (
-	"fmt"
-	"strings"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 
 	forgejo "codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	fg "dappco.re/go/core/scm/forge"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Issues command flags.

cmd/forge/cmd_labels.go

@@ -1,12 +1,12 @@
 package forge
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
 	forgejo "codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	fg "dappco.re/go/core/scm/forge"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Labels command flags.

cmd/forge/cmd_migrate.go

@@ -1,12 +1,12 @@
 package forge
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
 	forgejo "codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	fg "dappco.re/go/core/scm/forge"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Migrate command flags.

cmd/forge/cmd_orgs.go

@@ -1,10 +1,10 @@
 package forge
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	fg "dappco.re/go/core/scm/forge"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // addOrgsCommand adds the 'orgs' subcommand for listing organisations.

cmd/forge/cmd_prs.go

@@ -1,13 +1,13 @@
 package forge
 
 import (
-	"fmt"
-	"strings"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 
 	forgejo "codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	fg "dappco.re/go/core/scm/forge"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // PRs command flags.

cmd/forge/cmd_repos.go

@@ -1,12 +1,12 @@
 package forge
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
 	forgejo "codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	fg "dappco.re/go/core/scm/forge"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Repos command flags.

cmd/forge/cmd_status.go

@@ -1,10 +1,10 @@
 package forge
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	fg "dappco.re/go/core/scm/forge"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // addStatusCommand adds the 'status' subcommand for instance info.

cmd/forge/cmd_sync.go

@@ -1,12 +1,12 @@
 package forge
 
 import (
-	"fmt"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	os "dappco.re/go/core/scm/internal/ax/osx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
+	exec "golang.org/x/sys/execabs"
 	"net/url"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
 
 	coreerr "dappco.re/go/core/log"
 	"dappco.re/go/core/scm/agentci"

cmd/forge/cmd_sync_test.go

@@ -1,7 +1,7 @@
 package forge
 
 import (
-	"path/filepath"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
 	"testing"
 
 	"github.com/stretchr/testify/assert"

cmd/forge/helpers.go

@@ -1,8 +1,8 @@
 package forge
 
 import (
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"path"
-	"strings"
 
 	"forge.lthn.ai/core/cli/pkg/cli"
 )

cmd/gitea/cmd_config.go

@@ -1,10 +1,10 @@
 package gitea
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	gt "dappco.re/go/core/scm/gitea"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Config command flags.

cmd/gitea/cmd_gitea.go

@@ -30,6 +30,7 @@ var (
 )
 
 // AddGiteaCommands registers the 'gitea' command and all subcommands.
+// Usage example: AddGiteaCommands(...)
 func AddGiteaCommands(root *cli.Command) {
 	giteaCmd := &cli.Command{
 		Use:   "gitea",

cmd/gitea/cmd_issues.go

@@ -1,13 +1,13 @@
 package gitea
 
 import (
-	"fmt"
-	"strings"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 
 	"code.gitea.io/sdk/gitea"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	gt "dappco.re/go/core/scm/gitea"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Issues command flags.

cmd/gitea/cmd_mirror.go

@@ -1,12 +1,12 @@
 package gitea
 
 import (
-	"fmt"
-	"os/exec"
-	"strings"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
+	exec "golang.org/x/sys/execabs"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	gt "dappco.re/go/core/scm/gitea"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Mirror command flags.

cmd/gitea/cmd_prs.go

@@ -1,13 +1,13 @@
 package gitea
 
 import (
-	"fmt"
-	"strings"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 
 	sdk "code.gitea.io/sdk/gitea"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	gt "dappco.re/go/core/scm/gitea"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // PRs command flags.

cmd/gitea/cmd_repos.go

@@ -1,10 +1,10 @@
 package gitea
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	gt "dappco.re/go/core/scm/gitea"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 // Repos command flags.

cmd/gitea/cmd_sync.go

@@ -1,12 +1,12 @@
 package gitea
 
 import (
-	"fmt"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	os "dappco.re/go/core/scm/internal/ax/osx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
+	exec "golang.org/x/sys/execabs"
 	"net/url"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"strings"
 
 	coreerr "dappco.re/go/core/log"
 	"dappco.re/go/core/scm/agentci"

cmd/gitea/cmd_sync_test.go

@@ -1,7 +1,7 @@
 package gitea
 
 import (
-	"path/filepath"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
 	"testing"
 
 	"github.com/stretchr/testify/assert"

cmd/scm/cmd_compile.go

@@ -2,13 +2,13 @@ package scm
 
 import (
 	"crypto/ed25519"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"encoding/hex"
-	"os/exec"
-	"strings"
+	exec "golang.org/x/sys/execabs"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	"dappco.re/go/core/io"
 	"dappco.re/go/core/scm/manifest"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 func addCompileCommand(parent *cli.Command) {

cmd/scm/cmd_export.go

@@ -1,11 +1,11 @@
 package scm
 
 import (
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	"dappco.re/go/core/io"
 	"dappco.re/go/core/scm/manifest"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 func addExportCommand(parent *cli.Command) {

cmd/scm/cmd_index.go

@@ -1,11 +1,11 @@
 package scm
 
 import (
-	"fmt"
-	"path/filepath"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 
-	"forge.lthn.ai/core/cli/pkg/cli"
 	"dappco.re/go/core/scm/marketplace"
+	"forge.lthn.ai/core/cli/pkg/cli"
 )
 
 func addIndexCommand(parent *cli.Command) {

cmd/scm/cmd_scm.go

@@ -25,6 +25,7 @@ var (
 )
 
 // AddScmCommands registers the 'scm' command and all subcommands.
+// Usage example: AddScmCommands(...)
 func AddScmCommands(root *cli.Command) {
 	scmCmd := &cli.Command{
 		Use:   "scm",

collect/bitcointalk.go

@@ -2,11 +2,11 @@ package collect
 
 import (
 	"context"
-	"fmt"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"iter"
 	"net/http"
-	"path/filepath"
-	"strings"
 	"time"
 
 	core "dappco.re/go/core/log"
@@ -20,6 +20,7 @@ var httpClient = &http.Client{
 }
 
 // BitcoinTalkCollector collects forum posts from BitcoinTalk.
+// Usage example: var value BitcoinTalkCollector
 type BitcoinTalkCollector struct {
 	// TopicID is the numeric topic identifier.
 	TopicID string
@@ -281,6 +282,7 @@ func formatPostMarkdown(num int, post btPost) string {
 
 // ParsePostsFromHTML parses BitcoinTalk posts from raw HTML content.
 // This is exported for testing purposes.
+// Usage example: ParsePostsFromHTML(...)
 func ParsePostsFromHTML(htmlContent string) ([]btPost, error) {
 	doc, err := html.Parse(strings.NewReader(htmlContent))
 	if err != nil {
@@ -290,14 +292,17 @@ func ParsePostsFromHTML(htmlContent string) ([]btPost, error) {
 }
 
 // FormatPostMarkdown is exported for testing purposes.
+// Usage example: FormatPostMarkdown(...)
 func FormatPostMarkdown(num int, author, date, content string) string {
 	return formatPostMarkdown(num, btPost{Author: author, Date: date, Content: content})
 }
 
 // FetchPageFunc is an injectable function type for fetching pages, used in testing.
+// Usage example: var value FetchPageFunc
 type FetchPageFunc func(ctx context.Context, url string) ([]btPost, error)
 
 // BitcoinTalkCollectorWithFetcher wraps BitcoinTalkCollector with a custom fetcher for testing.
+// Usage example: var value BitcoinTalkCollectorWithFetcher
 type BitcoinTalkCollectorWithFetcher struct {
 	BitcoinTalkCollector
 	Fetcher FetchPageFunc
@@ -305,6 +310,7 @@ type BitcoinTalkCollectorWithFetcher struct {
 
 // SetHTTPClient replaces the package-level HTTP client.
 // Use this in tests to inject a custom transport or timeout.
+// Usage example: SetHTTPClient(...)
 func SetHTTPClient(c *http.Client) {
 	httpClient = c
 }

collect/bitcointalk_http_test.go

@@ -2,10 +2,10 @@ package collect
 
 import (
 	"context"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"net/http"
 	"net/http/httptest"
-	"strings"
 	"testing"
 
 	"dappco.re/go/core/io"

collect/collect.go

@@ -6,12 +6,13 @@ package collect
 
 import (
 	"context"
-	"path/filepath"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
 
 	"dappco.re/go/core/io"
 )
 
 // Collector is the interface all collection sources implement.
+// Usage example: var value Collector
 type Collector interface {
 	// Name returns a human-readable name for this collector.
 	Name() string
@@ -21,6 +22,7 @@ type Collector interface {
 }
 
 // Config holds shared configuration for all collectors.
+// Usage example: var value Config
 type Config struct {
 	// Output is the storage medium for writing collected data.
 	Output io.Medium
@@ -45,6 +47,7 @@ type Config struct {
 }
 
 // Result holds the output of a collection run.
+// Usage example: var value Result
 type Result struct {
 	// Source identifies which collector produced this result.
 	Source string
@@ -65,6 +68,7 @@ type Result struct {
 // NewConfig creates a Config with sensible defaults.
 // It initialises a MockMedium for output if none is provided,
 // sets up a rate limiter, state tracker, and event dispatcher.
+// Usage example: NewConfig(...)
 func NewConfig(outputDir string) *Config {
 	m := io.NewMockMedium()
 	return &Config{
@@ -77,6 +81,7 @@ func NewConfig(outputDir string) *Config {
 }
 
 // NewConfigWithMedium creates a Config using the specified storage medium.
+// Usage example: NewConfigWithMedium(...)
 func NewConfigWithMedium(m io.Medium, outputDir string) *Config {
 	return &Config{
 		Output:     m,
@@ -88,6 +93,7 @@ func NewConfigWithMedium(m io.Medium, outputDir string) *Config {
 }
 
 // MergeResults combines multiple results into a single aggregated result.
+// Usage example: MergeResults(...)
 func MergeResults(source string, results ...*Result) *Result {
 	merged := &Result{Source: source}
 	for _, r := range results {

collect/coverage_boost_test.go

@@ -2,7 +2,7 @@ package collect
 
 import (
 	"context"
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
 	"net/http"
 	"net/http/httptest"
 	"testing"

collect/coverage_phase2_test.go

@@ -2,13 +2,14 @@ package collect
 
 import (
 	"context"
-	"encoding/json"
-	"fmt"
+	core "dappco.re/go/core"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	goio "io"
 	"io/fs"
 	"net/http"
 	"net/http/httptest"
-	"strings"
 	"testing"
 	"time"
 
@@ -17,6 +18,14 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+func testErr(msg string) error {
+	return core.E("collect.test", msg, nil)
+}
+
+func testErrf(format string, args ...any) error {
+	return core.E("collect.test", fmt.Sprintf(format, args...), nil)
+}
+
 // errorMedium wraps MockMedium and injects errors on specific operations.
 type errorMedium struct {
 	*io.MockMedium
@@ -50,16 +59,18 @@ func (e *errorMedium) Read(path string) (string, error) {
 	}
 	return e.MockMedium.Read(path)
 }
-func (e *errorMedium) FileGet(path string) (string, error)             { return e.MockMedium.FileGet(path) }
-func (e *errorMedium) FileSet(path, content string) error              { return e.MockMedium.FileSet(path, content) }
-func (e *errorMedium) Delete(path string) error                        { return e.MockMedium.Delete(path) }
-func (e *errorMedium) DeleteAll(path string) error                     { return e.MockMedium.DeleteAll(path) }
-func (e *errorMedium) Rename(old, new string) error                    { return e.MockMedium.Rename(old, new) }
-func (e *errorMedium) Stat(path string) (fs.FileInfo, error)           { return e.MockMedium.Stat(path) }
-func (e *errorMedium) Open(path string) (fs.File, error)               { return e.MockMedium.Open(path) }
-func (e *errorMedium) Create(path string) (goio.WriteCloser, error)    { return e.MockMedium.Create(path) }
-func (e *errorMedium) Append(path string) (goio.WriteCloser, error)    { return e.MockMedium.Append(path) }
-func (e *errorMedium) ReadStream(path string) (goio.ReadCloser, error) { return e.MockMedium.ReadStream(path) }
+func (e *errorMedium) FileGet(path string) (string, error)          { return e.MockMedium.FileGet(path) }
+func (e *errorMedium) FileSet(path, content string) error           { return e.MockMedium.FileSet(path, content) }
+func (e *errorMedium) Delete(path string) error                     { return e.MockMedium.Delete(path) }
+func (e *errorMedium) DeleteAll(path string) error                  { return e.MockMedium.DeleteAll(path) }
+func (e *errorMedium) Rename(old, new string) error                 { return e.MockMedium.Rename(old, new) }
+func (e *errorMedium) Stat(path string) (fs.FileInfo, error)        { return e.MockMedium.Stat(path) }
+func (e *errorMedium) Open(path string) (fs.File, error)            { return e.MockMedium.Open(path) }
+func (e *errorMedium) Create(path string) (goio.WriteCloser, error) { return e.MockMedium.Create(path) }
+func (e *errorMedium) Append(path string) (goio.WriteCloser, error) { return e.MockMedium.Append(path) }
+func (e *errorMedium) ReadStream(path string) (goio.ReadCloser, error) {
+	return e.MockMedium.ReadStream(path)
+}
 func (e *errorMedium) WriteStream(path string) (goio.WriteCloser, error) {
 	return e.MockMedium.WriteStream(path)
 }
@@ -74,7 +85,7 @@ type errorLimiterWaiter struct{}
 // --- Processor: list error ---
 
 func TestProcessor_Process_Bad_ListError(t *testing.T) {
-	em := &errorMedium{MockMedium: io.NewMockMedium(), listErr: fmt.Errorf("list denied")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), listErr: testErr("list denied")}
 	cfg := &Config{Output: em, OutputDir: "/output", Dispatcher: NewDispatcher()}
 
 	p := &Processor{Source: "test", Dir: "/input"}
@@ -86,7 +97,7 @@ func TestProcessor_Process_Bad_ListError(t *testing.T) {
 // --- Processor: ensureDir error ---
 
 func TestProcessor_Process_Bad_EnsureDirError(t *testing.T) {
-	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: fmt.Errorf("mkdir denied")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: testErr("mkdir denied")}
 	// Need to ensure List returns entries
 	em.MockMedium.Dirs["/input"] = true
 	em.MockMedium.Files["/input/test.html"] = "<h1>Test</h1>"
@@ -121,7 +132,7 @@ func TestProcessor_Process_Bad_ContextCancelledDuringLoop(t *testing.T) {
 // --- Processor: read error during file processing ---
 
 func TestProcessor_Process_Bad_ReadError(t *testing.T) {
-	em := &errorMedium{MockMedium: io.NewMockMedium(), readErr: fmt.Errorf("read denied")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), readErr: testErr("read denied")}
 	em.MockMedium.Dirs["/input"] = true
 	em.MockMedium.Files["/input/test.html"] = "<h1>Test</h1>"
 
@@ -154,7 +165,7 @@ func TestProcessor_Process_Bad_InvalidJSONFile(t *testing.T) {
 // --- Processor: write error during output ---
 
 func TestProcessor_Process_Bad_WriteError(t *testing.T) {
-	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: fmt.Errorf("disk full")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: testErr("disk full")}
 	em.MockMedium.Dirs["/input"] = true
 	em.MockMedium.Files["/input/page.html"] = "<h1>Title</h1>"
 
@@ -255,13 +266,13 @@ func TestPapersCollector_CollectIACR_Bad_WriteError(t *testing.T) {
 	httpClient = &http.Client{Transport: transport}
 	defer func() { httpClient = old }()
 
-	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: fmt.Errorf("disk full")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: testErr("disk full")}
 	cfg := &Config{Output: em, OutputDir: "/output", Dispatcher: NewDispatcher()}
 	cfg.Limiter = nil
 
 	p := &PapersCollector{Source: PaperSourceIACR, Query: "test"}
 	result, err := p.Collect(context.Background(), cfg)
-	require.NoError(t, err) // Write errors increment Errors, not returned
+	require.NoError(t, err)           // Write errors increment Errors, not returned
 	assert.Equal(t, 2, result.Errors) // 2 papers both fail to write
 }
 
@@ -279,7 +290,7 @@ func TestPapersCollector_CollectIACR_Bad_EnsureDirError(t *testing.T) {
 	httpClient = &http.Client{Transport: transport}
 	defer func() { httpClient = old }()
 
-	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: fmt.Errorf("mkdir denied")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: testErr("mkdir denied")}
 	cfg := &Config{Output: em, OutputDir: "/output", Dispatcher: NewDispatcher()}
 	cfg.Limiter = nil
 
@@ -303,7 +314,7 @@ func TestPapersCollector_CollectArXiv_Bad_WriteError(t *testing.T) {
 	httpClient = &http.Client{Transport: transport}
 	defer func() { httpClient = old }()
 
-	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: fmt.Errorf("disk full")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: testErr("disk full")}
 	cfg := &Config{Output: em, OutputDir: "/output", Dispatcher: NewDispatcher()}
 	cfg.Limiter = nil
 
@@ -327,7 +338,7 @@ func TestPapersCollector_CollectArXiv_Bad_EnsureDirError(t *testing.T) {
 	httpClient = &http.Client{Transport: transport}
 	defer func() { httpClient = old }()
 
-	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: fmt.Errorf("mkdir denied")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: testErr("mkdir denied")}
 	cfg := &Config{Output: em, OutputDir: "/output", Dispatcher: NewDispatcher()}
 	cfg.Limiter = nil
 
@@ -453,7 +464,7 @@ func TestMarketCollector_Collect_Bad_WriteError(t *testing.T) {
 	coinGeckoBaseURL = server.URL
 	defer func() { coinGeckoBaseURL = oldURL }()
 
-	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: fmt.Errorf("disk full")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: testErr("disk full")}
 	cfg := &Config{Output: em, OutputDir: "/output", Dispatcher: NewDispatcher()}
 	cfg.Limiter = nil
 
@@ -477,7 +488,7 @@ func TestMarketCollector_Collect_Bad_EnsureDirError(t *testing.T) {
 	coinGeckoBaseURL = server.URL
 	defer func() { coinGeckoBaseURL = oldURL }()
 
-	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: fmt.Errorf("mkdir denied")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: testErr("mkdir denied")}
 	cfg := &Config{Output: em, OutputDir: "/output", Dispatcher: NewDispatcher()}
 	cfg.Limiter = nil
 
@@ -552,7 +563,7 @@ func TestMarketCollector_Collect_Good_HistoricalCustomDate(t *testing.T) {
 // --- BitcoinTalk: EnsureDir error ---
 
 func TestBitcoinTalkCollector_Collect_Bad_EnsureDirError(t *testing.T) {
-	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: fmt.Errorf("mkdir denied")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), ensureDirErr: testErr("mkdir denied")}
 	cfg := &Config{Output: em, OutputDir: "/output", Dispatcher: NewDispatcher()}
 	cfg.Limiter = nil
 
@@ -592,13 +603,13 @@ func TestBitcoinTalkCollector_Collect_Bad_WriteErrorOnPosts(t *testing.T) {
 	httpClient = &http.Client{Transport: transport}
 	defer func() { httpClient = old }()
 
-	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: fmt.Errorf("disk full")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: testErr("disk full")}
 	cfg := &Config{Output: em, OutputDir: "/output", Dispatcher: NewDispatcher()}
 	cfg.Limiter = nil
 
 	b := &BitcoinTalkCollector{TopicID: "12345"}
 	result, err := b.Collect(context.Background(), cfg)
-	require.NoError(t, err) // write errors are counted
+	require.NoError(t, err)           // write errors are counted
 	assert.Equal(t, 3, result.Errors) // 3 posts all fail to write
 	assert.Equal(t, 0, result.Items)
 }
@@ -968,34 +979,44 @@ func TestBitcoinTalkCollector_Collect_Bad_LimiterBlocks(t *testing.T) {
 // writeCountMedium fails after N successful writes.
 type writeCountMedium struct {
 	*io.MockMedium
-	writeCount   int
-	failAfterN   int
+	writeCount int
+	failAfterN int
 }
 
 func (w *writeCountMedium) Write(path, content string) error {
 	w.writeCount++
 	if w.writeCount > w.failAfterN {
-		return fmt.Errorf("write %d: disk full", w.writeCount)
+		return testErrf("write %d: disk full", w.writeCount)
 	}
 	return w.MockMedium.Write(path, content)
 }
-func (w *writeCountMedium) EnsureDir(path string) error              { return w.MockMedium.EnsureDir(path) }
-func (w *writeCountMedium) Read(path string) (string, error)         { return w.MockMedium.Read(path) }
-func (w *writeCountMedium) List(path string) ([]fs.DirEntry, error)  { return w.MockMedium.List(path) }
-func (w *writeCountMedium) IsFile(path string) bool                  { return w.MockMedium.IsFile(path) }
-func (w *writeCountMedium) FileGet(path string) (string, error)      { return w.MockMedium.FileGet(path) }
-func (w *writeCountMedium) FileSet(path, content string) error       { return w.MockMedium.FileSet(path, content) }
-func (w *writeCountMedium) Delete(path string) error                 { return w.MockMedium.Delete(path) }
-func (w *writeCountMedium) DeleteAll(path string) error              { return w.MockMedium.DeleteAll(path) }
-func (w *writeCountMedium) Rename(old, new string) error             { return w.MockMedium.Rename(old, new) }
-func (w *writeCountMedium) Stat(path string) (fs.FileInfo, error)    { return w.MockMedium.Stat(path) }
-func (w *writeCountMedium) Open(path string) (fs.File, error)        { return w.MockMedium.Open(path) }
-func (w *writeCountMedium) Create(path string) (goio.WriteCloser, error) { return w.MockMedium.Create(path) }
-func (w *writeCountMedium) Append(path string) (goio.WriteCloser, error) { return w.MockMedium.Append(path) }
-func (w *writeCountMedium) ReadStream(path string) (goio.ReadCloser, error) { return w.MockMedium.ReadStream(path) }
-func (w *writeCountMedium) WriteStream(path string) (goio.WriteCloser, error) { return w.MockMedium.WriteStream(path) }
-func (w *writeCountMedium) Exists(path string) bool                  { return w.MockMedium.Exists(path) }
-func (w *writeCountMedium) IsDir(path string) bool                   { return w.MockMedium.IsDir(path) }
+func (w *writeCountMedium) EnsureDir(path string) error             { return w.MockMedium.EnsureDir(path) }
+func (w *writeCountMedium) Read(path string) (string, error)        { return w.MockMedium.Read(path) }
+func (w *writeCountMedium) List(path string) ([]fs.DirEntry, error) { return w.MockMedium.List(path) }
+func (w *writeCountMedium) IsFile(path string) bool                 { return w.MockMedium.IsFile(path) }
+func (w *writeCountMedium) FileGet(path string) (string, error)     { return w.MockMedium.FileGet(path) }
+func (w *writeCountMedium) FileSet(path, content string) error {
+	return w.MockMedium.FileSet(path, content)
+}
+func (w *writeCountMedium) Delete(path string) error              { return w.MockMedium.Delete(path) }
+func (w *writeCountMedium) DeleteAll(path string) error           { return w.MockMedium.DeleteAll(path) }
+func (w *writeCountMedium) Rename(old, new string) error          { return w.MockMedium.Rename(old, new) }
+func (w *writeCountMedium) Stat(path string) (fs.FileInfo, error) { return w.MockMedium.Stat(path) }
+func (w *writeCountMedium) Open(path string) (fs.File, error)     { return w.MockMedium.Open(path) }
+func (w *writeCountMedium) Create(path string) (goio.WriteCloser, error) {
+	return w.MockMedium.Create(path)
+}
+func (w *writeCountMedium) Append(path string) (goio.WriteCloser, error) {
+	return w.MockMedium.Append(path)
+}
+func (w *writeCountMedium) ReadStream(path string) (goio.ReadCloser, error) {
+	return w.MockMedium.ReadStream(path)
+}
+func (w *writeCountMedium) WriteStream(path string) (goio.WriteCloser, error) {
+	return w.MockMedium.WriteStream(path)
+}
+func (w *writeCountMedium) Exists(path string) bool { return w.MockMedium.Exists(path) }
+func (w *writeCountMedium) IsDir(path string) bool  { return w.MockMedium.IsDir(path) }
 
 // Test that the summary.md write error in collectCurrent is handled.
 func TestMarketCollector_Collect_Bad_SummaryWriteError(t *testing.T) {
@@ -1075,7 +1096,7 @@ func TestMarketCollector_Collect_Bad_HistoricalWriteError(t *testing.T) {
 // --- State: Save write error ---
 
 func TestState_Save_Bad_WriteError(t *testing.T) {
-	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: fmt.Errorf("disk full")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: testErr("disk full")}
 	s := NewState(em, "/state.json")
 	s.Set("test", &StateEntry{Source: "test", Items: 1})
 
@@ -1134,7 +1155,7 @@ func TestBitcoinTalkCollector_Collect_Good_ZeroPostsPage(t *testing.T) {
 // --- Excavator: state save error after collection ---
 
 func TestExcavator_Run_Bad_StateSaveError(t *testing.T) {
-	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: fmt.Errorf("state write failed")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), writeErr: testErr("state write failed")}
 	cfg := &Config{
 		Output:     io.NewMockMedium(), // Use regular medium for output
 		OutputDir:  "/output",
@@ -1158,7 +1179,7 @@ func TestExcavator_Run_Bad_StateSaveError(t *testing.T) {
 // --- State: Load with read error ---
 
 func TestState_Load_Bad_ReadError(t *testing.T) {
-	em := &errorMedium{MockMedium: io.NewMockMedium(), readErr: fmt.Errorf("read denied")}
+	em := &errorMedium{MockMedium: io.NewMockMedium(), readErr: testErr("read denied")}
 	em.MockMedium.Files["/state.json"] = "{}" // File exists but read will fail
 
 	s := NewState(em, "/state.json")

collect/events.go

@@ -8,22 +8,28 @@ import (
 // Event types used by the collection subsystem.
 const (
 	// EventStart is emitted when a collector begins its run.
+	// Usage example: _ = EventStart
 	EventStart = "start"
 
 	// EventProgress is emitted to report incremental progress.
+	// Usage example: _ = EventProgress
 	EventProgress = "progress"
 
 	// EventItem is emitted when a single item is collected.
+	// Usage example: _ = EventItem
 	EventItem = "item"
 
 	// EventError is emitted when an error occurs during collection.
+	// Usage example: _ = EventError
 	EventError = "error"
 
 	// EventComplete is emitted when a collector finishes its run.
+	// Usage example: _ = EventComplete
 	EventComplete = "complete"
 )
 
 // Event represents a collection event.
+// Usage example: var value Event
 type Event struct {
 	// Type is one of the Event* constants.
 	Type string `json:"type"`
@@ -42,16 +48,19 @@ type Event struct {
 }
 
 // EventHandler handles collection events.
+// Usage example: var value EventHandler
 type EventHandler func(Event)
 
 // Dispatcher manages event dispatch. Handlers are registered per event type
 // and are called synchronously when an event is emitted.
+// Usage example: var value Dispatcher
 type Dispatcher struct {
 	mu       sync.RWMutex
 	handlers map[string][]EventHandler
 }
 
 // NewDispatcher creates a new event dispatcher.
+// Usage example: NewDispatcher(...)
 func NewDispatcher() *Dispatcher {
 	return &Dispatcher{
 		handlers: make(map[string][]EventHandler),

collect/excavate.go

@@ -2,7 +2,7 @@ package collect
 
 import (
 	"context"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 	"time"
 
 	core "dappco.re/go/core/log"
@@ -11,6 +11,7 @@ import (
 // Excavator runs multiple collectors as a coordinated operation.
 // It provides sequential execution with rate limit respect, state tracking
 // for resume support, and aggregated results.
+// Usage example: var value Excavator
 type Excavator struct {
 	// Collectors is the list of collectors to run.
 	Collectors []Collector

collect/excavate_test.go

@@ -2,7 +2,8 @@ package collect
 
 import (
 	"context"
-	"fmt"
+	core "dappco.re/go/core"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 	"testing"
 
 	"dappco.re/go/core/io"
@@ -126,7 +127,7 @@ func TestExcavator_Run_Good_WithErrors(t *testing.T) {
 	cfg.Limiter = nil
 
 	c1 := &mockCollector{name: "good", items: 5}
-	c2 := &mockCollector{name: "bad", err: fmt.Errorf("network error")}
+	c2 := &mockCollector{name: "bad", err: core.E("collect.mockCollector.Collect", "network error", nil)}
 	c3 := &mockCollector{name: "also-good", items: 3}
 
 	e := &Excavator{

collect/github.go

@@ -2,11 +2,11 @@ package collect
 
 import (
 	"context"
-	"encoding/json"
-	"fmt"
-	"os/exec"
-	"path/filepath"
-	"strings"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
+	exec "golang.org/x/sys/execabs"
 	"time"
 
 	core "dappco.re/go/core/log"
@@ -38,6 +38,7 @@ type ghRepo struct {
 }
 
 // GitHubCollector collects issues and PRs from GitHub repositories.
+// Usage example: var value GitHubCollector
 type GitHubCollector struct {
 	// Org is the GitHub organisation.
 	Org string

collect/market.go

@@ -2,11 +2,11 @@ package collect
 
 import (
 	"context"
-	"encoding/json"
-	"fmt"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"net/http"
-	"path/filepath"
-	"strings"
 	"time"
 
 	core "dappco.re/go/core/log"
@@ -17,6 +17,7 @@ import (
 var coinGeckoBaseURL = "https://api.coingecko.com/api/v3"
 
 // MarketCollector collects market data from CoinGecko.
+// Usage example: var value MarketCollector
 type MarketCollector struct {
 	// CoinID is the CoinGecko coin identifier (e.g. "bitcoin", "ethereum").
 	CoinID string
@@ -272,6 +273,7 @@ func formatMarketSummary(data *coinData) string {
 }
 
 // FormatMarketSummary is exported for testing.
+// Usage example: FormatMarketSummary(...)
 func FormatMarketSummary(data *coinData) string {
 	return formatMarketSummary(data)
 }

collect/market_extra_test.go

@@ -2,7 +2,7 @@ package collect
 
 import (
 	"context"
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
 	"net/http"
 	"net/http/httptest"
 	"testing"

collect/market_test.go

@@ -2,7 +2,7 @@ package collect
 
 import (
 	"context"
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
 	"net/http"
 	"net/http/httptest"
 	"testing"

collect/papers.go

@@ -2,13 +2,13 @@ package collect
 
 import (
 	"context"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"encoding/xml"
-	"fmt"
 	"iter"
 	"net/http"
 	"net/url"
-	"path/filepath"
-	"strings"
 
 	core "dappco.re/go/core/log"
 	"golang.org/x/net/html"
@@ -16,12 +16,16 @@ import (
 
 // Paper source identifiers.
 const (
-	PaperSourceIACR  = "iacr"
+	// Usage example: _ = PaperSourceIACR
+	PaperSourceIACR = "iacr"
+	// Usage example: _ = PaperSourceArXiv
 	PaperSourceArXiv = "arxiv"
-	PaperSourceAll   = "all"
+	// Usage example: _ = PaperSourceAll
+	PaperSourceAll = "all"
 )
 
 // PapersCollector collects papers from IACR and arXiv.
+// Usage example: var value PapersCollector
 type PapersCollector struct {
 	// Source is one of PaperSourceIACR, PaperSourceArXiv, or PaperSourceAll.
 	Source string
@@ -403,6 +407,7 @@ func formatPaperMarkdown(ppr paper) string {
 }
 
 // FormatPaperMarkdown is exported for testing.
+// Usage example: FormatPaperMarkdown(...)
 func FormatPaperMarkdown(title string, authors []string, date, paperURL, source, abstract string) string {
 	return formatPaperMarkdown(paper{
 		Title:    title,

collect/papers_http_test.go

@@ -2,9 +2,9 @@ package collect
 
 import (
 	"context"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"net/http"
 	"net/http/httptest"
-	"strings"
 	"testing"
 
 	"dappco.re/go/core/io"

collect/process.go

@@ -2,18 +2,19 @@ package collect
 
 import (
 	"context"
-	"encoding/json"
-	"fmt"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"maps"
-	"path/filepath"
 	"slices"
-	"strings"
 
 	core "dappco.re/go/core/log"
 	"golang.org/x/net/html"
 )
 
 // Processor converts collected data to clean markdown.
+// Usage example: var value Processor
 type Processor struct {
 	// Source identifies the data source directory to process.
 	Source string
@@ -331,11 +332,13 @@ func jsonValueToMarkdown(b *strings.Builder, data any, depth int) {
 }
 
 // HTMLToMarkdown is exported for testing.
+// Usage example: HTMLToMarkdown(...)
 func HTMLToMarkdown(content string) (string, error) {
 	return htmlToMarkdown(content)
 }
 
 // JSONToMarkdown is exported for testing.
+// Usage example: JSONToMarkdown(...)
 func JSONToMarkdown(content string) (string, error) {
 	return jsonToMarkdown(content)
 }

collect/ratelimit.go

@@ -2,11 +2,11 @@ package collect
 
 import (
 	"context"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
+	exec "golang.org/x/sys/execabs"
 	"maps"
-	"os/exec"
 	"strconv"
-	"strings"
 	"sync"
 	"time"
 
@@ -14,6 +14,7 @@ import (
 )
 
 // RateLimiter tracks per-source rate limiting to avoid overwhelming APIs.
+// Usage example: var value RateLimiter
 type RateLimiter struct {
 	mu     sync.Mutex
 	delays map[string]time.Duration
@@ -30,6 +31,7 @@ var defaultDelays = map[string]time.Duration{
 }
 
 // NewRateLimiter creates a limiter with default delays.
+// Usage example: NewRateLimiter(...)
 func NewRateLimiter() *RateLimiter {
 	delays := make(map[string]time.Duration, len(defaultDelays))
 	maps.Copy(delays, defaultDelays)

collect/state.go

@@ -1,17 +1,18 @@
 package collect
 
 import (
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
 	"sync"
 	"time"
 
-	core "dappco.re/go/core/log"
 	"dappco.re/go/core/io"
+	core "dappco.re/go/core/log"
 )
 
 // State tracks collection progress for incremental runs.
 // It persists entries to disk so that subsequent runs can resume
 // where they left off.
+// Usage example: var value State
 type State struct {
 	mu      sync.Mutex
 	medium  io.Medium
@@ -20,6 +21,7 @@ type State struct {
 }
 
 // StateEntry tracks state for one source.
+// Usage example: var value StateEntry
 type StateEntry struct {
 	// Source identifies the collector.
 	Source string `json:"source"`
@@ -39,6 +41,7 @@ type StateEntry struct {
 
 // NewState creates a state tracker that persists to the given path
 // using the provided storage medium.
+// Usage example: NewState(...)
 func NewState(m io.Medium, path string) *State {
 	return &State{
 		medium:  m,

forge/client.go

@@ -15,6 +15,7 @@ import (
 )
 
 // Client wraps the Forgejo SDK client with config-based auth.
+// Usage example: var value Client
 type Client struct {
 	api   *forgejo.Client
 	url   string
@@ -22,6 +23,7 @@ type Client struct {
 }
 
 // New creates a new Forgejo API client for the given URL and token.
+// Usage example: New(...)
 func New(url, token string) (*Client, error) {
 	api, err := forgejo.NewClient(url, forgejo.SetToken(token))
 	if err != nil {

forge/client_test.go

@@ -1,8 +1,8 @@
 package forge
 
 import (
-	"encoding/json"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -132,7 +132,7 @@ func TestClient_SetPRDraft_Bad_ConnectionRefused(t *testing.T) {
 	assert.Error(t, err)
 }
 
-func TestClient_SetPRDraft_URLConstruction(t *testing.T) {
+func TestClient_SetPRDraft_Good_URLConstruction(t *testing.T) {
 	// Verify the URL is constructed correctly by checking the request path.
 	var capturedPath string
 	mux := http.NewServeMux()
@@ -156,7 +156,7 @@ func TestClient_SetPRDraft_URLConstruction(t *testing.T) {
 	assert.Equal(t, "/api/v1/repos/my-org/my-repo/pulls/42", capturedPath)
 }
 
-func TestClient_SetPRDraft_AuthHeader(t *testing.T) {
+func TestClient_SetPRDraft_Good_AuthHeader(t *testing.T) {
 	// Verify the authorisation header is set correctly.
 	var capturedAuth string
 	mux := http.NewServeMux()
@@ -182,7 +182,7 @@ func TestClient_SetPRDraft_AuthHeader(t *testing.T) {
 
 // --- PRMeta and Comment struct tests ---
 
-func TestPRMeta_Fields(t *testing.T) {
+func TestPRMeta_Good_Fields(t *testing.T) {
 	meta := &PRMeta{
 		Number:       42,
 		Title:        "Test PR",
@@ -208,7 +208,7 @@ func TestPRMeta_Fields(t *testing.T) {
 	assert.Equal(t, 5, meta.CommentCount)
 }
 
-func TestComment_Fields(t *testing.T) {
+func TestComment_Good_Fields(t *testing.T) {
 	comment := Comment{
 		ID:     123,
 		Author: "reviewer",
@@ -222,7 +222,7 @@ func TestComment_Fields(t *testing.T) {
 
 // --- MergePullRequest merge style mapping ---
 
-func TestMergePullRequest_StyleMapping(t *testing.T) {
+func TestMergePullRequest_Good_StyleMapping(t *testing.T) {
 	// We can't easily test the SDK call, but we can verify the method
 	// errors when the server returns failure. This exercises the style mapping code.
 	tests := []struct {
@@ -260,7 +260,7 @@ func TestMergePullRequest_StyleMapping(t *testing.T) {
 
 // --- ListIssuesOpts defaulting ---
 
-func TestListIssuesOpts_Defaults(t *testing.T) {
+func TestListIssuesOpts_Good_Defaults(t *testing.T) {
 	tests := []struct {
 		name          string
 		opts          ListIssuesOpts
@@ -432,13 +432,13 @@ func TestClient_CreatePullRequest_Bad_ServerError(t *testing.T) {
 
 // --- commentPageSize constant test ---
 
-func TestCommentPageSize(t *testing.T) {
+func TestCommentPageSize_Good(t *testing.T) {
 	assert.Equal(t, 50, commentPageSize, "comment page size should be 50")
 }
 
 // --- ListPullRequests state mapping ---
 
-func TestListPullRequests_StateMapping(t *testing.T) {
+func TestListPullRequests_Good_StateMapping(t *testing.T) {
 	// Verify state mapping via error path (server returns error).
 	tests := []struct {
 		name  string

forge/config.go

@@ -1,19 +1,22 @@
 package forge
 
 import (
-	"os"
+	os "dappco.re/go/core/scm/internal/ax/osx"
 
-	"forge.lthn.ai/core/config"
 	"dappco.re/go/core/log"
+	"forge.lthn.ai/core/config"
 )
 
 const (
 	// ConfigKeyURL is the config key for the Forgejo instance URL.
+	// Usage example: _ = ConfigKeyURL
 	ConfigKeyURL = "forge.url"
 	// ConfigKeyToken is the config key for the Forgejo API token.
+	// Usage example: _ = ConfigKeyToken
 	ConfigKeyToken = "forge.token"
 
 	// DefaultURL is the default Forgejo instance URL.
+	// Usage example: _ = DefaultURL
 	DefaultURL = "http://localhost:4000"
 )
 
@@ -22,6 +25,8 @@ const (
 //  1. ~/.core/config.yaml keys: forge.token, forge.url
 //  2. FORGE_TOKEN + FORGE_URL environment variables (override config file)
 //  3. Provided flag overrides (highest priority; pass empty to skip)
+//
+// Usage example: NewFromConfig(...)
 func NewFromConfig(flagURL, flagToken string) (*Client, error) {
 	url, token, err := ResolveConfig(flagURL, flagToken)
 	if err != nil {
@@ -37,6 +42,7 @@ func NewFromConfig(flagURL, flagToken string) (*Client, error) {
 
 // ResolveConfig resolves the Forgejo URL and token from all config sources.
 // Flag values take highest priority, then env vars, then config file.
+// Usage example: ResolveConfig(...)
 func ResolveConfig(flagURL, flagToken string) (url, token string, err error) {
 	// Start with config file values
 	cfg, cfgErr := config.New()
@@ -70,6 +76,7 @@ func ResolveConfig(flagURL, flagToken string) (url, token string, err error) {
 }
 
 // SaveConfig persists the Forgejo URL and/or token to the config file.
+// Usage example: SaveConfig(...)
 func SaveConfig(url, token string) error {
 	cfg, err := config.New()
 	if err != nil {

forge/config_test.go

@@ -68,7 +68,7 @@ func TestResolveConfig_Good_URLDefaultsWhenEmpty(t *testing.T) {
 	assert.Equal(t, "some-token", token)
 }
 
-func TestConstants(t *testing.T) {
+func TestConstants_Good(t *testing.T) {
 	assert.Equal(t, "forge.url", ConfigKeyURL)
 	assert.Equal(t, "forge.token", ConfigKeyToken)
 	assert.Equal(t, "http://localhost:4000", DefaultURL)

forge/issues.go

@@ -9,6 +9,7 @@ import (
 )
 
 // ListIssuesOpts configures issue listing.
+// Usage example: var value ListIssuesOpts
 type ListIssuesOpts struct {
 	State  string   // "open", "closed", "all"
 	Labels []string // filter by label names

forge/labels.go

@@ -1,7 +1,7 @@
 package forge
 
 import (
-	"strings"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 
 	forgejo "codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2"
 

forge/meta.go

@@ -10,6 +10,7 @@ import (
 
 // PRMeta holds structural signals from a pull request,
 // used by the pipeline MetaReader for AI-driven workflows.
+// Usage example: var value PRMeta
 type PRMeta struct {
 	Number       int64
 	Title        string
@@ -26,6 +27,7 @@ type PRMeta struct {
 }
 
 // Comment represents a comment with metadata.
+// Usage example: var value Comment
 type Comment struct {
 	ID        int64
 	Author    string

forge/prs.go

@@ -2,8 +2,8 @@ package forge
 
 import (
 	"bytes"
-	"encoding/json"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
 	"net/http"
 	"net/url"
 	"strconv"

forge/prs_test.go

@@ -1,10 +1,10 @@
 package forge
 
 import (
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"net/http"
 	"net/http/httptest"
-	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"

forge/testhelper_test.go

@@ -1,10 +1,10 @@
 package forge
 
 import (
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"net/http"
 	"net/http/httptest"
-	"strings"
 	"testing"
 )
 

git/git.go

@@ -4,17 +4,18 @@ package git
 import (
 	"bytes"
 	"context"
+	os "dappco.re/go/core/scm/internal/ax/osx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
+	exec "golang.org/x/sys/execabs"
 	"io"
 	"iter"
-	"os"
-	"os/exec"
 	"slices"
 	"strconv"
-	"strings"
 	"sync"
 )
 
 // RepoStatus represents the git status of a single repository.
+// Usage example: var value RepoStatus
 type RepoStatus struct {
 	Name      string
 	Path      string
@@ -43,6 +44,7 @@ func (s *RepoStatus) HasUnpulled() bool {
 }
 
 // StatusOptions configures the status check.
+// Usage example: var value StatusOptions
 type StatusOptions struct {
 	// Paths is a list of repo paths to check
 	Paths []string
@@ -51,6 +53,7 @@ type StatusOptions struct {
 }
 
 // Status checks git status for multiple repositories in parallel.
+// Usage example: Status(...)
 func Status(ctx context.Context, opts StatusOptions) []RepoStatus {
 	var wg sync.WaitGroup
 	results := make([]RepoStatus, len(opts.Paths))
@@ -72,6 +75,7 @@ func Status(ctx context.Context, opts StatusOptions) []RepoStatus {
 }
 
 // StatusIter returns an iterator over git status for multiple repositories.
+// Usage example: StatusIter(...)
 func StatusIter(ctx context.Context, opts StatusOptions) iter.Seq[RepoStatus] {
 	return func(yield func(RepoStatus) bool) {
 		results := Status(ctx, opts)
@@ -156,17 +160,20 @@ func getAheadBehind(ctx context.Context, path string) (ahead, behind int) {
 
 // Push pushes commits for a single repository.
 // Uses interactive mode to support SSH passphrase prompts.
+// Usage example: Push(...)
 func Push(ctx context.Context, path string) error {
 	return gitInteractive(ctx, path, "push")
 }
 
 // Pull pulls changes for a single repository.
 // Uses interactive mode to support SSH passphrase prompts.
+// Usage example: Pull(...)
 func Pull(ctx context.Context, path string) error {
 	return gitInteractive(ctx, path, "pull", "--rebase")
 }
 
 // IsNonFastForward checks if an error is a non-fast-forward rejection.
+// Usage example: IsNonFastForward(...)
 func IsNonFastForward(err error) bool {
 	if err == nil {
 		return false
@@ -201,6 +208,7 @@ func gitInteractive(ctx context.Context, dir string, args ...string) error {
 }
 
 // PushResult represents the result of a push operation.
+// Usage example: var value PushResult
 type PushResult struct {
 	Name    string
 	Path    string
@@ -210,11 +218,13 @@ type PushResult struct {
 
 // PushMultiple pushes multiple repositories sequentially.
 // Sequential because SSH passphrase prompts need user interaction.
+// Usage example: PushMultiple(...)
 func PushMultiple(ctx context.Context, paths []string, names map[string]string) []PushResult {
 	return slices.Collect(PushMultipleIter(ctx, paths, names))
 }
 
 // PushMultipleIter returns an iterator that pushes repositories sequentially and yields results.
+// Usage example: PushMultipleIter(...)
 func PushMultipleIter(ctx context.Context, paths []string, names map[string]string) iter.Seq[PushResult] {
 	return func(yield func(PushResult) bool) {
 		for _, path := range paths {
@@ -263,6 +273,7 @@ func gitCommand(ctx context.Context, dir string, args ...string) (string, error)
 }
 
 // GitError wraps a git command error with stderr output.
+// Usage example: var value GitError
 type GitError struct {
 	Err    error
 	Stderr string

git/service.go

@@ -11,49 +11,58 @@ import (
 // Queries for git service
 
 // QueryStatus requests git status for paths.
+// Usage example: var value QueryStatus
 type QueryStatus struct {
 	Paths []string
 	Names map[string]string
 }
 
 // QueryDirtyRepos requests repos with uncommitted changes.
+// Usage example: var value QueryDirtyRepos
 type QueryDirtyRepos struct{}
 
 // QueryAheadRepos requests repos with unpushed commits.
+// Usage example: var value QueryAheadRepos
 type QueryAheadRepos struct{}
 
 // Tasks for git service
 
 // TaskPush requests git push for a path.
+// Usage example: var value TaskPush
 type TaskPush struct {
 	Path string
 	Name string
 }
 
 // TaskPull requests git pull for a path.
+// Usage example: var value TaskPull
 type TaskPull struct {
 	Path string
 	Name string
 }
 
 // TaskPushMultiple requests git push for multiple paths.
+// Usage example: var value TaskPushMultiple
 type TaskPushMultiple struct {
 	Paths []string
 	Names map[string]string
 }
 
 // ServiceOptions for configuring the git service.
+// Usage example: var value ServiceOptions
 type ServiceOptions struct {
 	WorkDir string
 }
 
 // Service provides git operations as a Core service.
+// Usage example: var value Service
 type Service struct {
 	*core.ServiceRuntime[ServiceOptions]
 	lastStatus []RepoStatus
 }
 
 // NewService creates a git service factory.
+// Usage example: NewService(...)
 func NewService(opts ServiceOptions) func(*core.Core) (any, error) {
 	return func(c *core.Core) (any, error) {
 		return &Service{

gitea/client.go

@@ -15,12 +15,14 @@ import (
 )
 
 // Client wraps the Gitea SDK client with config-based auth.
+// Usage example: var value Client
 type Client struct {
 	api *gitea.Client
 	url string
 }
 
 // New creates a new Gitea API client for the given URL and token.
+// Usage example: New(...)
 func New(url, token string) (*Client, error) {
 	api, err := gitea.NewClient(url, gitea.SetToken(token))
 	if err != nil {

gitea/config.go

@@ -1,19 +1,22 @@
 package gitea
 
 import (
-	"os"
+	os "dappco.re/go/core/scm/internal/ax/osx"
 
-	"forge.lthn.ai/core/config"
 	"dappco.re/go/core/log"
+	"forge.lthn.ai/core/config"
 )
 
 const (
 	// ConfigKeyURL is the config key for the Gitea instance URL.
+	// Usage example: _ = ConfigKeyURL
 	ConfigKeyURL = "gitea.url"
 	// ConfigKeyToken is the config key for the Gitea API token.
+	// Usage example: _ = ConfigKeyToken
 	ConfigKeyToken = "gitea.token"
 
 	// DefaultURL is the default Gitea instance URL.
+	// Usage example: _ = DefaultURL
 	DefaultURL = "https://gitea.snider.dev"
 )
 
@@ -22,6 +25,8 @@ const (
 //  1. ~/.core/config.yaml keys: gitea.token, gitea.url
 //  2. GITEA_TOKEN + GITEA_URL environment variables (override config file)
 //  3. Provided flag overrides (highest priority; pass empty to skip)
+//
+// Usage example: NewFromConfig(...)
 func NewFromConfig(flagURL, flagToken string) (*Client, error) {
 	url, token, err := ResolveConfig(flagURL, flagToken)
 	if err != nil {
@@ -37,6 +42,7 @@ func NewFromConfig(flagURL, flagToken string) (*Client, error) {
 
 // ResolveConfig resolves the Gitea URL and token from all config sources.
 // Flag values take highest priority, then env vars, then config file.
+// Usage example: ResolveConfig(...)
 func ResolveConfig(flagURL, flagToken string) (url, token string, err error) {
 	// Start with config file values
 	cfg, cfgErr := config.New()
@@ -70,6 +76,7 @@ func ResolveConfig(flagURL, flagToken string) (url, token string, err error) {
 }
 
 // SaveConfig persists the Gitea URL and/or token to the config file.
+// Usage example: SaveConfig(...)
 func SaveConfig(url, token string) error {
 	cfg, err := config.New()
 	if err != nil {

gitea/config_test.go

@@ -66,7 +66,7 @@ func TestResolveConfig_Good_URLDefaultsWhenEmpty(t *testing.T) {
 	assert.Equal(t, "some-token", token)
 }
 
-func TestConstants(t *testing.T) {
+func TestConstants_Good(t *testing.T) {
 	assert.Equal(t, "gitea.url", ConfigKeyURL)
 	assert.Equal(t, "gitea.token", ConfigKeyToken)
 	assert.Equal(t, "https://gitea.snider.dev", DefaultURL)

gitea/coverage_boost_test.go

@@ -1,7 +1,7 @@
 package gitea
 
 import (
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
 	"net/http"
 	"net/http/httptest"
 	"testing"
@@ -146,12 +146,12 @@ func newPRMetaWithManyCommentsServer(t *testing.T) *httptest.Server {
 	mux.HandleFunc("/api/v1/repos/test-org/test-repo/pulls/1", func(w http.ResponseWriter, r *http.Request) {
 		jsonResponse(w, map[string]any{
 			"id": 1, "number": 1, "title": "Many Comments PR", "state": "open",
-			"merged": false,
-			"head":   map[string]any{"ref": "feature", "label": "feature"},
-			"base":   map[string]any{"ref": "main", "label": "main"},
-			"user":   map[string]any{"login": "author"},
-			"labels": []map[string]any{},
-			"assignees": []map[string]any{},
+			"merged":     false,
+			"head":       map[string]any{"ref": "feature", "label": "feature"},
+			"base":       map[string]any{"ref": "main", "label": "main"},
+			"user":       map[string]any{"login": "author"},
+			"labels":     []map[string]any{},
+			"assignees":  []map[string]any{},
 			"created_at": "2026-01-15T10:00:00Z",
 			"updated_at": "2026-01-16T12:00:00Z",
 		})

gitea/issues.go

@@ -9,6 +9,7 @@ import (
 )
 
 // ListIssuesOpts configures issue listing.
+// Usage example: var value ListIssuesOpts
 type ListIssuesOpts struct {
 	State string // "open", "closed", "all"
 	Page  int

gitea/issues_test.go

@@ -163,7 +163,7 @@ func TestClient_GetPullRequest_Bad_ServerError(t *testing.T) {
 
 // --- ListIssuesOpts defaulting ---
 
-func TestListIssuesOpts_Defaults(t *testing.T) {
+func TestListIssuesOpts_Good_Defaults(t *testing.T) {
 	tests := []struct {
 		name          string
 		opts          ListIssuesOpts

gitea/meta.go

@@ -10,6 +10,7 @@ import (
 
 // PRMeta holds structural signals from a pull request,
 // used by the pipeline MetaReader for AI-driven workflows.
+// Usage example: var value PRMeta
 type PRMeta struct {
 	Number       int64
 	Title        string
@@ -26,6 +27,7 @@ type PRMeta struct {
 }
 
 // Comment represents a comment with metadata.
+// Usage example: var value Comment
 type Comment struct {
 	ID        int64
 	Author    string

gitea/meta_test.go

@@ -74,7 +74,7 @@ func TestClient_GetIssueBody_Bad_ServerError(t *testing.T) {
 
 // --- PRMeta struct tests ---
 
-func TestPRMeta_Fields(t *testing.T) {
+func TestPRMeta_Good_Fields(t *testing.T) {
 	meta := &PRMeta{
 		Number:       42,
 		Title:        "Test PR",
@@ -100,7 +100,7 @@ func TestPRMeta_Fields(t *testing.T) {
 	assert.Equal(t, 5, meta.CommentCount)
 }
 
-func TestComment_Fields(t *testing.T) {
+func TestComment_Good_Fields(t *testing.T) {
 	comment := Comment{
 		ID:     123,
 		Author: "reviewer",
@@ -112,6 +112,6 @@ func TestComment_Fields(t *testing.T) {
 	assert.Equal(t, "LGTM", comment.Body)
 }
 
-func TestCommentPageSize(t *testing.T) {
+func TestCommentPageSize_Good(t *testing.T) {
 	assert.Equal(t, 50, commentPageSize, "comment page size should be 50")
 }

gitea/testhelper_test.go

@@ -1,10 +1,10 @@
 package gitea
 
 import (
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"net/http"
 	"net/http/httptest"
-	"strings"
 	"testing"
 )
 
@@ -130,7 +130,7 @@ func newGiteaMux() *http.ServeMux {
 		w.WriteHeader(http.StatusCreated)
 		jsonResponse(w, map[string]any{
 			"id": 40, "name": "mirrored-repo", "full_name": "test-org/mirrored-repo",
-			"owner": map[string]any{"login": "test-org"},
+			"owner":  map[string]any{"login": "test-org"},
 			"mirror": true,
 		})
 	})

go.mod

@@ -14,8 +14,10 @@ require (
 	forge.lthn.ai/core/cli v0.3.7
 	forge.lthn.ai/core/config v0.1.8
 	github.com/gin-gonic/gin v1.12.0
+	github.com/goccy/go-json v0.10.6
 	github.com/stretchr/testify v1.11.1
 	golang.org/x/net v0.52.0
+	golang.org/x/sys v0.42.0
 	gopkg.in/yaml.v3 v3.0.1
 )
 
@@ -86,7 +88,6 @@ require (
 	github.com/go-playground/universal-translator v0.18.1 // indirect
 	github.com/go-playground/validator/v10 v10.30.1 // indirect
 	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
-	github.com/goccy/go-json v0.10.6 // indirect
 	github.com/goccy/go-yaml v1.19.2 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/context v1.1.2 // indirect
@@ -145,7 +146,6 @@ require (
 	golang.org/x/mod v0.34.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sync v0.20.0 // indirect
-	golang.org/x/sys v0.42.0 // indirect
 	golang.org/x/term v0.41.0 // indirect
 	golang.org/x/text v0.35.0 // indirect
 	golang.org/x/tools v0.43.0 // indirect

internal/ax/filepathx/filepathx.go

@@ -0,0 +1,53 @@
+package filepathx
+
+import (
+	"path"
+	"syscall"
+)
+
+// Separator mirrors filepath.Separator for Unix-style Core paths.
+// Usage example: _ = Separator
+const Separator = '/'
+
+// Abs mirrors filepath.Abs for the paths used in this repo.
+// Usage example: Abs(...)
+func Abs(p string) (string, error) {
+	if path.IsAbs(p) {
+		return path.Clean(p), nil
+	}
+	cwd, err := syscall.Getwd()
+	if err != nil {
+		return "", err
+	}
+	return path.Clean(path.Join(cwd, p)), nil
+}
+
+// Base mirrors filepath.Base.
+// Usage example: Base(...)
+func Base(p string) string {
+	return path.Base(p)
+}
+
+// Clean mirrors filepath.Clean.
+// Usage example: Clean(...)
+func Clean(p string) string {
+	return path.Clean(p)
+}
+
+// Dir mirrors filepath.Dir.
+// Usage example: Dir(...)
+func Dir(p string) string {
+	return path.Dir(p)
+}
+
+// Ext mirrors filepath.Ext.
+// Usage example: Ext(...)
+func Ext(p string) string {
+	return path.Ext(p)
+}
+
+// Join mirrors filepath.Join.
+// Usage example: Join(...)
+func Join(elem ...string) string {
+	return path.Join(elem...)
+}

internal/ax/fmtx/fmtx.go

@@ -0,0 +1,38 @@
+package fmtx
+
+import (
+	"io"
+
+	core "dappco.re/go/core"
+	"dappco.re/go/core/scm/internal/ax/stdio"
+)
+
+// Sprint mirrors fmt.Sprint using Core primitives.
+// Usage example: Sprint(...)
+func Sprint(args ...any) string {
+	return core.Sprint(args...)
+}
+
+// Sprintf mirrors fmt.Sprintf using Core primitives.
+// Usage example: Sprintf(...)
+func Sprintf(format string, args ...any) string {
+	return core.Sprintf(format, args...)
+}
+
+// Fprintf mirrors fmt.Fprintf using Core primitives.
+// Usage example: Fprintf(...)
+func Fprintf(w io.Writer, format string, args ...any) (int, error) {
+	return io.WriteString(w, Sprintf(format, args...))
+}
+
+// Printf mirrors fmt.Printf.
+// Usage example: Printf(...)
+func Printf(format string, args ...any) (int, error) {
+	return Fprintf(stdio.Stdout, format, args...)
+}
+
+// Println mirrors fmt.Println.
+// Usage example: Println(...)
+func Println(args ...any) (int, error) {
+	return io.WriteString(stdio.Stdout, Sprint(args...)+"\n")
+}

internal/ax/jsonx/jsonx.go

@@ -0,0 +1,37 @@
+package jsonx
+
+import (
+	"io"
+
+	json "github.com/goccy/go-json"
+)
+
+// Marshal mirrors encoding/json.Marshal.
+// Usage example: Marshal(...)
+func Marshal(v any) ([]byte, error) {
+	return json.Marshal(v)
+}
+
+// MarshalIndent mirrors encoding/json.MarshalIndent.
+// Usage example: MarshalIndent(...)
+func MarshalIndent(v any, prefix, indent string) ([]byte, error) {
+	return json.MarshalIndent(v, prefix, indent)
+}
+
+// NewDecoder mirrors encoding/json.NewDecoder.
+// Usage example: NewDecoder(...)
+func NewDecoder(r io.Reader) *json.Decoder {
+	return json.NewDecoder(r)
+}
+
+// NewEncoder mirrors encoding/json.NewEncoder.
+// Usage example: NewEncoder(...)
+func NewEncoder(w io.Writer) *json.Encoder {
+	return json.NewEncoder(w)
+}
+
+// Unmarshal mirrors encoding/json.Unmarshal.
+// Usage example: Unmarshal(...)
+func Unmarshal(data []byte, v any) error {
+	return json.Unmarshal(data, v)
+}

internal/ax/osx/osx.go

@@ -0,0 +1,111 @@
+package osx
+
+import (
+	"io"
+	"io/fs"
+	"os/user"
+	"syscall"
+
+	core "dappco.re/go/core"
+	coreio "dappco.re/go/core/io"
+	"dappco.re/go/core/scm/internal/ax/stdio"
+)
+
+const (
+	// Usage example: _ = O_APPEND
+	O_APPEND = syscall.O_APPEND
+	// Usage example: _ = O_CREATE
+	O_CREATE = syscall.O_CREAT
+	// Usage example: _ = O_WRONLY
+	O_WRONLY = syscall.O_WRONLY
+)
+
+// Stdin exposes process stdin without importing os.
+// Usage example: _ = Stdin
+var Stdin = stdio.Stdin
+
+// Stdout exposes process stdout without importing os.
+// Usage example: _ = Stdout
+var Stdout = stdio.Stdout
+
+// Stderr exposes process stderr without importing os.
+// Usage example: _ = Stderr
+var Stderr = stdio.Stderr
+
+// Getenv mirrors os.Getenv.
+// Usage example: Getenv(...)
+func Getenv(key string) string {
+	value, _ := syscall.Getenv(key)
+	return value
+}
+
+// Getwd mirrors os.Getwd.
+// Usage example: Getwd(...)
+func Getwd() (string, error) {
+	return syscall.Getwd()
+}
+
+// IsNotExist mirrors os.IsNotExist.
+// Usage example: IsNotExist(...)
+func IsNotExist(err error) bool {
+	return core.Is(err, fs.ErrNotExist)
+}
+
+// MkdirAll mirrors os.MkdirAll.
+// Usage example: MkdirAll(...)
+func MkdirAll(path string, _ fs.FileMode) error {
+	return coreio.Local.EnsureDir(path)
+}
+
+// Open mirrors os.Open.
+// Usage example: Open(...)
+func Open(path string) (fs.File, error) {
+	return coreio.Local.Open(path)
+}
+
+// OpenFile mirrors the append/create/write mode used in this repo.
+// Usage example: OpenFile(...)
+func OpenFile(path string, flag int, _ fs.FileMode) (io.WriteCloser, error) {
+	if flag&O_APPEND != 0 {
+		return coreio.Local.Append(path)
+	}
+	return coreio.Local.Create(path)
+}
+
+// ReadDir mirrors os.ReadDir.
+// Usage example: ReadDir(...)
+func ReadDir(path string) ([]fs.DirEntry, error) {
+	return coreio.Local.List(path)
+}
+
+// ReadFile mirrors os.ReadFile.
+// Usage example: ReadFile(...)
+func ReadFile(path string) ([]byte, error) {
+	content, err := coreio.Local.Read(path)
+	return []byte(content), err
+}
+
+// Stat mirrors os.Stat.
+// Usage example: Stat(...)
+func Stat(path string) (fs.FileInfo, error) {
+	return coreio.Local.Stat(path)
+}
+
+// UserHomeDir mirrors os.UserHomeDir.
+// Usage example: UserHomeDir(...)
+func UserHomeDir() (string, error) {
+	if home := Getenv("HOME"); home != "" {
+		return home, nil
+	}
+	current, err := user.Current()
+	if err != nil {
+		return "", err
+	}
+	return current.HomeDir, nil
+}
+
+// WriteFile mirrors os.WriteFile.
+// Usage example: WriteFile(...)
+func WriteFile(path string, data []byte, perm fs.FileMode) error {
+	return coreio.Local.WriteMode(path, string(data), perm)
+}

internal/ax/stdio/stdio.go

@@ -0,0 +1,38 @@
+package stdio
+
+import (
+	"io"
+	"syscall"
+)
+
+type fdReader struct {
+	fd int
+}
+
+func (r fdReader) Read(p []byte) (int, error) {
+	n, err := syscall.Read(r.fd, p)
+	if n == 0 && err == nil {
+		return 0, io.EOF
+	}
+	return n, err
+}
+
+type fdWriter struct {
+	fd int
+}
+
+func (w fdWriter) Write(p []byte) (int, error) {
+	return syscall.Write(w.fd, p)
+}
+
+// Stdin exposes process stdin without importing os.
+// Usage example: _ = Stdin
+var Stdin io.Reader = fdReader{fd: 0}
+
+// Stdout exposes process stdout without importing os.
+// Usage example: _ = Stdout
+var Stdout io.Writer = fdWriter{fd: 1}
+
+// Stderr exposes process stderr without importing os.
+// Usage example: _ = Stderr
+var Stderr io.Writer = fdWriter{fd: 2}

internal/ax/stringsx/stringsx.go

@@ -0,0 +1,149 @@
+package stringsx
+
+import (
+	"bufio"
+	"bytes"
+	"iter"
+
+	core "dappco.re/go/core"
+)
+
+// Builder provides a strings.Builder-like type without importing strings.
+// Usage example: var value Builder
+type Builder = bytes.Buffer
+
+// Contains mirrors strings.Contains.
+// Usage example: Contains(...)
+func Contains(s, substr string) bool {
+	return core.Contains(s, substr)
+}
+
+// ContainsAny mirrors strings.ContainsAny.
+// Usage example: ContainsAny(...)
+func ContainsAny(s, chars string) bool {
+	return bytes.IndexAny([]byte(s), chars) >= 0
+}
+
+// EqualFold mirrors strings.EqualFold.
+// Usage example: EqualFold(...)
+func EqualFold(s, t string) bool {
+	return bytes.EqualFold([]byte(s), []byte(t))
+}
+
+// Fields mirrors strings.Fields.
+// Usage example: Fields(...)
+func Fields(s string) []string {
+	scanner := bufio.NewScanner(NewReader(s))
+	scanner.Split(bufio.ScanWords)
+	fields := make([]string, 0)
+	for scanner.Scan() {
+		fields = append(fields, scanner.Text())
+	}
+	return fields
+}
+
+// HasPrefix mirrors strings.HasPrefix.
+// Usage example: HasPrefix(...)
+func HasPrefix(s, prefix string) bool {
+	return core.HasPrefix(s, prefix)
+}
+
+// HasSuffix mirrors strings.HasSuffix.
+// Usage example: HasSuffix(...)
+func HasSuffix(s, suffix string) bool {
+	return core.HasSuffix(s, suffix)
+}
+
+// Join mirrors strings.Join.
+// Usage example: Join(...)
+func Join(elems []string, sep string) string {
+	return core.Join(sep, elems...)
+}
+
+// LastIndex mirrors strings.LastIndex.
+// Usage example: LastIndex(...)
+func LastIndex(s, substr string) int {
+	return bytes.LastIndex([]byte(s), []byte(substr))
+}
+
+// NewReader mirrors strings.NewReader.
+// Usage example: NewReader(...)
+func NewReader(s string) *bytes.Reader {
+	return bytes.NewReader([]byte(s))
+}
+
+// Repeat mirrors strings.Repeat.
+// Usage example: Repeat(...)
+func Repeat(s string, count int) string {
+	if count <= 0 {
+		return ""
+	}
+	return string(bytes.Repeat([]byte(s), count))
+}
+
+// ReplaceAll mirrors strings.ReplaceAll.
+// Usage example: ReplaceAll(...)
+func ReplaceAll(s, old, new string) string {
+	return core.Replace(s, old, new)
+}
+
+// Replace mirrors strings.Replace for replace-all call sites.
+// Usage example: Replace(...)
+func Replace(s, old, new string, _ int) string {
+	return ReplaceAll(s, old, new)
+}
+
+// Split mirrors strings.Split.
+// Usage example: Split(...)
+func Split(s, sep string) []string {
+	return core.Split(s, sep)
+}
+
+// SplitN mirrors strings.SplitN.
+// Usage example: SplitN(...)
+func SplitN(s, sep string, n int) []string {
+	return core.SplitN(s, sep, n)
+}
+
+// SplitSeq mirrors strings.SplitSeq.
+// Usage example: SplitSeq(...)
+func SplitSeq(s, sep string) iter.Seq[string] {
+	parts := Split(s, sep)
+	return func(yield func(string) bool) {
+		for _, part := range parts {
+			if !yield(part) {
+				return
+			}
+		}
+	}
+}
+
+// ToLower mirrors strings.ToLower.
+// Usage example: ToLower(...)
+func ToLower(s string) string {
+	return core.Lower(s)
+}
+
+// ToUpper mirrors strings.ToUpper.
+// Usage example: ToUpper(...)
+func ToUpper(s string) string {
+	return core.Upper(s)
+}
+
+// TrimPrefix mirrors strings.TrimPrefix.
+// Usage example: TrimPrefix(...)
+func TrimPrefix(s, prefix string) string {
+	return core.TrimPrefix(s, prefix)
+}
+
+// TrimSpace mirrors strings.TrimSpace.
+// Usage example: TrimSpace(...)
+func TrimSpace(s string) string {
+	return core.Trim(s)
+}
+
+// TrimSuffix mirrors strings.TrimSuffix.
+// Usage example: TrimSuffix(...)
+func TrimSuffix(s, suffix string) string {
+	return core.TrimSuffix(s, suffix)
+}

jobrunner/forgejo/source.go

@@ -2,26 +2,29 @@ package forgejo
 
 import (
 	"context"
-	"fmt"
-	"strings"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 
+	"dappco.re/go/core/log"
 	"dappco.re/go/core/scm/forge"
 	"dappco.re/go/core/scm/jobrunner"
-	"dappco.re/go/core/log"
 )
 
 // Config configures a ForgejoSource.
+// Usage example: var value Config
 type Config struct {
 	Repos []string // "owner/repo" format
 }
 
 // ForgejoSource polls a Forgejo instance for pipeline signals from epic issues.
+// Usage example: var value ForgejoSource
 type ForgejoSource struct {
 	repos []string
 	forge *forge.Client
 }
 
 // New creates a ForgejoSource using the given forge client.
+// Usage example: New(...)
 func New(cfg Config, client *forge.Client) *ForgejoSource {
 	return &ForgejoSource{
 		repos: cfg.Repos,

jobrunner/forgejo/source_test.go

@@ -2,10 +2,10 @@ package forgejo
 
 import (
 	"context"
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"net/http"
 	"net/http/httptest"
-	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -35,7 +35,7 @@ func newTestClient(t *testing.T, url string) *forge.Client {
 	return client
 }
 
-func TestForgejoSource_Name(t *testing.T) {
+func TestForgejoSource_Good_Name(t *testing.T) {
 	s := New(Config{}, nil)
 	assert.Equal(t, "forgejo", s.Name())
 }
@@ -106,7 +106,7 @@ func TestForgejoSource_Poll_Good(t *testing.T) {
 	assert.Equal(t, "abc123", sig.LastCommitSHA)
 }
 
-func TestForgejoSource_Poll_NoEpics(t *testing.T) {
+func TestForgejoSource_Poll_Good_NoEpics(t *testing.T) {
 	srv := httptest.NewServer(withVersion(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		_ = json.NewEncoder(w).Encode([]any{})
@@ -152,18 +152,18 @@ func TestForgejoSource_Report_Good(t *testing.T) {
 	assert.Contains(t, capturedBody, "succeeded")
 }
 
-func TestParseEpicChildren(t *testing.T) {
+func TestParseEpicChildren_Good(t *testing.T) {
 	body := "## Tasks\n- [x] #1\n- [ ] #7\n- [ ] #8\n- [x] #3\n"
 	unchecked, checked := parseEpicChildren(body)
 	assert.Equal(t, []int{7, 8}, unchecked)
 	assert.Equal(t, []int{1, 3}, checked)
 }
 
-func TestFindLinkedPR(t *testing.T) {
+func TestFindLinkedPR_Good(t *testing.T) {
 	assert.Nil(t, findLinkedPR(nil, 7))
 }
 
-func TestSplitRepo(t *testing.T) {
+func TestSplitRepo_Good(t *testing.T) {
 	owner, repo, err := splitRepo("host-uk/core")
 	require.NoError(t, err)
 	assert.Equal(t, "host-uk", owner)

jobrunner/handlers/completion.go

@@ -2,7 +2,7 @@ package handlers
 
 import (
 	"context"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 	"time"
 
 	coreerr "dappco.re/go/core/log"
@@ -11,15 +11,18 @@ import (
 )
 
 const (
+	// Usage example: _ = ColorAgentComplete
 	ColorAgentComplete = "#0e8a16" // Green
 )
 
 // CompletionHandler manages issue state when an agent finishes work.
+// Usage example: var value CompletionHandler
 type CompletionHandler struct {
 	forge *forge.Client
 }
 
 // NewCompletionHandler creates a handler for agent completion events.
+// Usage example: NewCompletionHandler(...)
 func NewCompletionHandler(client *forge.Client) *CompletionHandler {
 	return &CompletionHandler{
 		forge: client,

jobrunner/handlers/dispatch.go

@@ -3,10 +3,10 @@ package handlers
 import (
 	"bytes"
 	"context"
-	"encoding/json"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"path"
-	"strings"
 	"time"
 
 	coreerr "dappco.re/go/core/log"
@@ -16,17 +16,24 @@ import (
 )
 
 const (
-	LabelAgentReady    = "agent-ready"
-	LabelInProgress    = "in-progress"
-	LabelAgentFailed   = "agent-failed"
+	// Usage example: _ = LabelAgentReady
+	LabelAgentReady = "agent-ready"
+	// Usage example: _ = LabelInProgress
+	LabelInProgress = "in-progress"
+	// Usage example: _ = LabelAgentFailed
+	LabelAgentFailed = "agent-failed"
+	// Usage example: _ = LabelAgentComplete
 	LabelAgentComplete = "agent-completed"
 
-	ColorInProgress  = "#1d76db" // Blue
+	// Usage example: _ = ColorInProgress
+	ColorInProgress = "#1d76db" // Blue
+	// Usage example: _ = ColorAgentFailed
 	ColorAgentFailed = "#c0392b" // Red
 )
 
 // DispatchTicket is the JSON payload written to the agent's queue.
 // The ForgeToken is transferred separately via a .env file with 0600 permissions.
+// Usage example: var value DispatchTicket
 type DispatchTicket struct {
 	ID           string `json:"id"`
 	RepoOwner    string `json:"repo_owner"`
@@ -46,6 +53,7 @@ type DispatchTicket struct {
 }
 
 // DispatchHandler dispatches coding work to remote agent machines via SSH.
+// Usage example: var value DispatchHandler
 type DispatchHandler struct {
 	forge    *forge.Client
 	forgeURL string
@@ -54,6 +62,7 @@ type DispatchHandler struct {
 }
 
 // NewDispatchHandler creates a handler that dispatches tickets to agent machines.
+// Usage example: NewDispatchHandler(...)
 func NewDispatchHandler(client *forge.Client, forgeURL, token string, spinner *agentci.Spinner) *DispatchHandler {
 	return &DispatchHandler{
 		forge:    client,

jobrunner/handlers/dispatch_test.go

@@ -2,11 +2,11 @@ package handlers
 
 import (
 	"context"
-	"encoding/json"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	os "dappco.re/go/core/scm/internal/ax/osx"
 	"net/http"
 	"net/http/httptest"
-	"os"
-	"path/filepath"
 	"strconv"
 	"testing"
 

jobrunner/handlers/enable_auto_merge.go

@@ -2,7 +2,7 @@ package handlers
 
 import (
 	"context"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 	"time"
 
 	"dappco.re/go/core/scm/forge"
@@ -10,11 +10,13 @@ import (
 )
 
 // EnableAutoMergeHandler merges a PR that is ready using squash strategy.
+// Usage example: var value EnableAutoMergeHandler
 type EnableAutoMergeHandler struct {
 	forge *forge.Client
 }
 
 // NewEnableAutoMergeHandler creates a handler that merges ready PRs.
+// Usage example: NewEnableAutoMergeHandler(...)
 func NewEnableAutoMergeHandler(f *forge.Client) *EnableAutoMergeHandler {
 	return &EnableAutoMergeHandler{forge: f}
 }

jobrunner/handlers/enable_auto_merge_test.go

@@ -2,7 +2,7 @@ package handlers
 
 import (
 	"context"
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
 	"net/http"
 	"net/http/httptest"
 	"testing"

jobrunner/handlers/publish_draft.go

@@ -2,7 +2,7 @@ package handlers
 
 import (
 	"context"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 	"time"
 
 	"dappco.re/go/core/scm/forge"
@@ -10,11 +10,13 @@ import (
 )
 
 // PublishDraftHandler marks a draft PR as ready for review once its checks pass.
+// Usage example: var value PublishDraftHandler
 type PublishDraftHandler struct {
 	forge *forge.Client
 }
 
 // NewPublishDraftHandler creates a handler that publishes draft PRs.
+// Usage example: NewPublishDraftHandler(...)
 func NewPublishDraftHandler(f *forge.Client) *PublishDraftHandler {
 	return &PublishDraftHandler{forge: f}
 }

jobrunner/handlers/resolve_threads.go

@@ -2,7 +2,7 @@ package handlers
 
 import (
 	"context"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 	"time"
 
 	forgejosdk "codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2"
@@ -15,11 +15,13 @@ import (
 // DismissReviewsHandler dismisses stale "request changes" reviews on a PR.
 // This replaces the GitHub-only ResolveThreadsHandler because Forgejo does
 // not have a thread resolution API.
+// Usage example: var value DismissReviewsHandler
 type DismissReviewsHandler struct {
 	forge *forge.Client
 }
 
 // NewDismissReviewsHandler creates a handler that dismisses stale reviews.
+// Usage example: NewDismissReviewsHandler(...)
 func NewDismissReviewsHandler(f *forge.Client) *DismissReviewsHandler {
 	return &DismissReviewsHandler{forge: f}
 }

jobrunner/handlers/resolve_threads_test.go

@@ -2,7 +2,7 @@ package handlers
 
 import (
 	"context"
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
 	"net/http"
 	"net/http/httptest"
 	"testing"

jobrunner/handlers/send_fix_command.go

@@ -2,7 +2,7 @@ package handlers
 
 import (
 	"context"
-	"fmt"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
 	"time"
 
 	"dappco.re/go/core/scm/forge"
@@ -11,11 +11,13 @@ import (
 
 // SendFixCommandHandler posts a comment on a PR asking for conflict or
 // review fixes.
+// Usage example: var value SendFixCommandHandler
 type SendFixCommandHandler struct {
 	forge *forge.Client
 }
 
 // NewSendFixCommandHandler creates a handler that posts fix commands.
+// Usage example: NewSendFixCommandHandler(...)
 func NewSendFixCommandHandler(f *forge.Client) *SendFixCommandHandler {
 	return &SendFixCommandHandler{forge: f}
 }

jobrunner/handlers/testhelper_test.go

@@ -1,8 +1,8 @@
 package handlers
 
 import (
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"net/http"
-	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/require"

jobrunner/handlers/tick_parent.go

@@ -2,8 +2,8 @@ package handlers
 
 import (
 	"context"
-	"fmt"
-	"strings"
+	fmt "dappco.re/go/core/scm/internal/ax/fmtx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"time"
 
 	forgejosdk "codeberg.org/mvdkleijn/forgejo-sdk/forgejo/v2"
@@ -15,11 +15,13 @@ import (
 
 // TickParentHandler ticks a child checkbox in the parent epic issue body
 // after the child's PR has been merged.
+// Usage example: var value TickParentHandler
 type TickParentHandler struct {
 	forge *forge.Client
 }
 
 // NewTickParentHandler creates a handler that ticks parent epic checkboxes.
+// Usage example: NewTickParentHandler(...)
 func NewTickParentHandler(f *forge.Client) *TickParentHandler {
 	return &TickParentHandler{forge: f}
 }

jobrunner/handlers/tick_parent_test.go

@@ -2,11 +2,11 @@ package handlers
 
 import (
 	"context"
-	"encoding/json"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"io"
 	"net/http"
 	"net/http/httptest"
-	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"

jobrunner/journal.go

@@ -1,21 +1,22 @@
 package jobrunner
 
 import (
-	"encoding/json"
-	"os"
-	"path/filepath"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	os "dappco.re/go/core/scm/internal/ax/osx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"regexp"
-	"strings"
 	"sync"
 
-	coreerr "dappco.re/go/core/log"
 	coreio "dappco.re/go/core/io"
+	coreerr "dappco.re/go/core/log"
 )
 
 // validPathComponent matches safe repo owner/name characters (alphanumeric, hyphen, underscore, dot).
 var validPathComponent = regexp.MustCompile(`^[a-zA-Z0-9][a-zA-Z0-9._-]*$`)
 
 // JournalEntry is a single line in the JSONL audit log.
+// Usage example: var value JournalEntry
 type JournalEntry struct {
 	Timestamp string         `json:"ts"`
 	Epic      int            `json:"epic"`
@@ -29,6 +30,7 @@ type JournalEntry struct {
 }
 
 // SignalSnapshot captures the structural state of a PR at the time of action.
+// Usage example: var value SignalSnapshot
 type SignalSnapshot struct {
 	PRState         string `json:"pr_state"`
 	IsDraft         bool   `json:"is_draft"`
@@ -39,6 +41,7 @@ type SignalSnapshot struct {
 }
 
 // ResultSnapshot captures the outcome of an action.
+// Usage example: var value ResultSnapshot
 type ResultSnapshot struct {
 	Success    bool   `json:"success"`
 	Error      string `json:"error,omitempty"`
@@ -46,12 +49,14 @@ type ResultSnapshot struct {
 }
 
 // Journal writes ActionResult entries to date-partitioned JSONL files.
+// Usage example: var value Journal
 type Journal struct {
 	baseDir string
 	mu      sync.Mutex
 }
 
 // NewJournal creates a new Journal rooted at baseDir.
+// Usage example: NewJournal(...)
 func NewJournal(baseDir string) (*Journal, error) {
 	if baseDir == "" {
 		return nil, coreerr.E("jobrunner.NewJournal", "base directory is required", nil)

jobrunner/journal_test.go

@@ -2,10 +2,10 @@ package jobrunner
 
 import (
 	"bufio"
-	"encoding/json"
-	"os"
-	"path/filepath"
-	"strings"
+	filepath "dappco.re/go/core/scm/internal/ax/filepathx"
+	json "dappco.re/go/core/scm/internal/ax/jsonx"
+	os "dappco.re/go/core/scm/internal/ax/osx"
+	strings "dappco.re/go/core/scm/internal/ax/stringsx"
 	"testing"
 	"time"
 

jobrunner/poller.go

@@ -9,6 +9,7 @@ import (
 )
 
 // PollerConfig configures a Poller.
+// Usage example: var value PollerConfig
 type PollerConfig struct {
 	Sources      []JobSource
 	Handlers     []JobHandler
@@ -18,6 +19,7 @@ type PollerConfig struct {
 }
 
 // Poller discovers signals from sources and dispatches them to handlers.
+// Usage example: var value Poller
 type Poller struct {
 	mu       sync.RWMutex
 	sources  []JobSource
@@ -29,6 +31,7 @@ type Poller struct {
 }
 
 // NewPoller creates a Poller from the given config.
+// Usage example: NewPoller(...)
 func NewPoller(cfg PollerConfig) *Poller {
 	interval := cfg.PollInterval
 	if interval <= 0 {