refactor(ax): modernize command docs

cmd/mining/cmd/doctor.go

@@ -16,7 +16,7 @@ import (
 const signpostFilename = ".installed-miners"
 
 // validateConfigPath("/home/alice/.config/lethean-desktop/miners/config.json") // nil
-// validateConfigPath("/tmp/config.json") // error
+// validateConfigPath("/tmp/config.json") // error because the path is outside XDG_CONFIG_HOME
 func validateConfigPath(configPath string) error {
 	expectedBase := filepath.Join(xdg.ConfigHome, "lethean-desktop")
 
@@ -29,7 +29,7 @@ func validateConfigPath(configPath string) error {
 	return nil
 }
 
-// doctorCmd.Use == "doctor" and RunE refreshes the local installation cache.
+// doctor refreshes the miner installation cache and refreshes the cached summary on disk.
 var doctorCmd = &cobra.Command{
 	Use:   "doctor",
 	Short: "Check and refresh the status of installed miners",

cmd/mining/cmd/list.go

@@ -6,7 +6,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// listCmd.Use == "list" and RunE prints running and available miners.
+// mining list prints the running miners and the installable miners.
 var listCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List running and available miners",

cmd/mining/cmd/peer.go

@@ -8,15 +8,14 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// findPeerByPartialID("a1b2c3") // defined in remote.go and used by peer subcommands
-// peerCmd.Use == "peer" and RunE groups peer-management subcommands.
+// peer add, peer list, peer remove, peer ping, and peer optimal live under this command group.
 var peerCmd = &cobra.Command{
 	Use:   "peer",
 	Short: "Manage peer nodes",
 	Long:  `Add, remove, and manage connections to peer nodes.`,
 }
 
-// peerAddCmd.Use == "add" and RunE registers a new peer by address.
+// peer add --address 10.0.0.2:9090 --name worker-1 registers a peer by address.
 var peerAddCmd = &cobra.Command{
 	Use:   "add",
 	Short: "Add a peer node",
@@ -65,7 +64,7 @@ to exchange public keys and establish a secure connection.`,
 	},
 }
 
-// peerListCmd.Use == "list" and RunE prints registered peers.
+// peer list prints the currently registered peers and their connection status.
 var peerListCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List registered peers",
@@ -106,7 +105,7 @@ var peerListCmd = &cobra.Command{
 	},
 }
 
-// peerRemoveCmd.Use == "remove <peer-id>" and RunE removes the selected peer.
+// peer remove a1b2c3d4e5f6 removes the selected peer from the registry.
 var peerRemoveCmd = &cobra.Command{
 	Use:   "remove <peer-id>",
 	Short: "Remove a peer from registry",
@@ -134,7 +133,7 @@ var peerRemoveCmd = &cobra.Command{
 	},
 }
 
-// peerPingCmd.Use == "ping <peer-id>" and RunE prints a ping placeholder.
+// peer ping a1b2c3d4e5f6 measures the selected peer's reachability.
 var peerPingCmd = &cobra.Command{
 	Use:   "ping <peer-id>",
 	Short: "Ping a peer and update metrics",
@@ -159,7 +158,7 @@ var peerPingCmd = &cobra.Command{
 	},
 }
 
-// peerOptimalCmd.Use == "optimal" and RunE prints the best peer by score.
+// peer optimal --count 4 prints the four best peers by score.
 var peerOptimalCmd = &cobra.Command{
 	Use:   "optimal",
 	Short: "Show the optimal peer based on metrics",

cmd/mining/cmd/remote.go

@@ -17,14 +17,14 @@ var (
 	controllerErr  error
 )
 
-// remoteCmd.Use == "remote" and RunE groups remote node commands.
+// remote status, remote start, remote stop, remote logs, remote connect, remote disconnect, and remote ping live under this command group.
 var remoteCmd = &cobra.Command{
 	Use:   "remote",
 	Short: "Control remote mining nodes",
 	Long:  `Send commands to remote worker nodes and retrieve their status.`,
 }
 
-// remoteStatusCmd.Use == "status [peer-id]" and RunE prints remote stats.
+// remote status a1b2c3d4e5f6 prints stats for one peer, while remote status prints the whole fleet.
 var remoteStatusCmd = &cobra.Command{
 	Use:   "status [peer-id]",
 	Short: "Get mining status from remote peers",
@@ -78,7 +78,7 @@ var remoteStatusCmd = &cobra.Command{
 	},
 }
 
-// remoteStartCmd.Use == "start <peer-id>" and RunE starts a miner on a peer.
+// remote start a1b2c3d4e5f6 --type xmrig --profile default starts a miner on the selected peer.
 var remoteStartCmd = &cobra.Command{
 	Use:   "start <peer-id>",
 	Short: "Start miner on remote peer",
@@ -112,7 +112,7 @@ var remoteStartCmd = &cobra.Command{
 	},
 }
 
-// remoteStopCmd.Use == "stop <peer-id> [miner-name]" and RunE stops a remote miner.
+// remote stop a1b2c3d4e5f6 xmrig-1 stops a named miner on the selected peer.
 var remoteStopCmd = &cobra.Command{
 	Use:   "stop <peer-id> [miner-name]",
 	Short: "Stop miner on remote peer",
@@ -151,7 +151,7 @@ var remoteStopCmd = &cobra.Command{
 	},
 }
 
-// remoteLogsCmd.Use == "logs <peer-id> <miner-name>" and RunE prints remote logs.
+// remote logs a1b2c3d4e5f6 xmrig-1 prints the first 100 log lines for the remote miner.
 var remoteLogsCmd = &cobra.Command{
 	Use:   "logs <peer-id> <miner-name>",
 	Short: "Get console logs from remote miner",
@@ -187,7 +187,7 @@ var remoteLogsCmd = &cobra.Command{
 	},
 }
 
-// remoteConnectCmd.Use == "connect <peer-id>" and RunE opens a peer connection.
+// remote connect a1b2c3d4e5f6 opens a WebSocket connection to the peer.
 var remoteConnectCmd = &cobra.Command{
 	Use:   "connect <peer-id>",
 	Short: "Connect to a remote peer",
@@ -215,7 +215,7 @@ var remoteConnectCmd = &cobra.Command{
 	},
 }
 
-// remoteDisconnectCmd.Use == "disconnect <peer-id>" and RunE closes a peer connection.
+// remote disconnect a1b2c3d4e5f6 closes the active peer connection.
 var remoteDisconnectCmd = &cobra.Command{
 	Use:   "disconnect <peer-id>",
 	Short: "Disconnect from a remote peer",
@@ -243,7 +243,7 @@ var remoteDisconnectCmd = &cobra.Command{
 	},
 }
 
-// remotePingCmd.Use == "ping <peer-id>" and RunE averages multiple ping samples.
+// remote ping a1b2c3d4e5f6 --count 4 averages four ping samples.
 var remotePingCmd = &cobra.Command{
 	Use:   "ping <peer-id>",
 	Short: "Ping a remote peer",
@@ -265,8 +265,8 @@ var remotePingCmd = &cobra.Command{
 
 		fmt.Printf("Pinging %s (%s)...\n", peer.Name, peer.Address)
 
-		var totalRTT float64
-		var successful int
+		var totalRoundTripMillis float64
+		var successfulPings int
 
 		for i := 0; i < count; i++ {
 			rtt, err := controller.PingPeer(peer.ID)
@@ -275,16 +275,16 @@ var remotePingCmd = &cobra.Command{
 				continue
 			}
 			fmt.Printf("  Ping %d: %.2f ms\n", i+1, rtt)
-			totalRTT += rtt
-			successful++
+			totalRoundTripMillis += rtt
+			successfulPings++
 
 			if i < count-1 {
 				time.Sleep(time.Second)
 			}
 		}
 
-		if successful > 0 {
-			fmt.Printf("\nAverage: %.2f ms (%d/%d successful)\n", totalRTT/float64(successful), successful, count)
+		if successfulPings > 0 {
+			fmt.Printf("\nAverage: %.2f ms (%d/%d successful)\n", totalRoundTripMillis/float64(successfulPings), successfulPings, count)
 		} else {
 			fmt.Println("\nAll pings failed.")
 		}

cmd/mining/cmd/serve.go

@@ -22,7 +22,7 @@ var (
 	namespace string
 )
 
-// serveCmd.Use == "serve" and RunE starts the HTTP API and shell.
+// mining serve starts the HTTP API and interactive shell.
 var serveCmd = &cobra.Command{
 	Use:   "serve",
 	Short: "Start the mining service and interactive shell",

cmd/mining/cmd/simulate.go

@@ -21,7 +21,7 @@ var (
 	simAlgorithm string
 )
 
-// simulateCmd.Use == "simulate" and RunE starts the service with fake miners.
+// mining simulate --count 3 --preset cpu-medium starts the API with fake miners.
 var simulateCmd = &cobra.Command{
 	Use:   "simulate",
 	Short: "Start the service with simulated miners for UI testing",

cmd/mining/cmd/start.go

@@ -13,7 +13,7 @@ var (
 	minerWallet string
 )
 
-// startCmd.Use == "start [miner_name]" and RunE starts the requested miner.
+// mining start xmrig --pool pool.example.com:3333 --wallet 44... starts the selected miner.
 var startCmd = &cobra.Command{
 	Use:   "start [miner_name]",
 	Short: "Start a new miner",

cmd/mining/cmd/status.go

@@ -9,7 +9,7 @@ import (
 	"golang.org/x/text/language"
 )
 
-// statusCmd.Use == "status [miner_name]" and RunE prints live miner stats.
+// mining status xmrig-rx_0 prints live stats for a running miner.
 var statusCmd = &cobra.Command{
 	Use:   "status [miner_name]",
 	Short: "Get status of a running miner",

cmd/mining/cmd/stop.go

@@ -7,7 +7,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// stopCmd.Use == "stop [miner_name]" and RunE stops the named miner.
+// mining stop xmrig-rx_0 stops the named miner.
 var stopCmd = &cobra.Command{
 	Use:   "stop [miner_name]",
 	Short: "Stop a running miner",

cmd/mining/cmd/uninstall.go

@@ -7,7 +7,7 @@ import (
 	"github.com/spf13/cobra"
 )
 
-// uninstallCmd.Use == "uninstall [miner_type]" and RunE removes the miner.
+// mining uninstall xmrig removes the miner and refreshes the cache.
 var uninstallCmd = &cobra.Command{
 	Use:   "uninstall [miner_type]",
 	Short: "Uninstall a miner",

cmd/mining/cmd/update.go

@@ -23,7 +23,7 @@ func validateUpdateConfigPath(configPath string) error {
 	return nil
 }
 
-// updateCmd.Use == "update" and RunE checks cached miner versions for upgrades.
+// mining update checks cached miner versions and reports available upgrades.
 var updateCmd = &cobra.Command{
 	Use:   "update",
 	Short: "Check for updates to installed miners",