fix(auth): polish error messages and add machine-account example

Address review feedback:
- Join missing-fields error with commas instead of Go's default slice formatting
- Add a hint to the OIDC discovery error pointing at --hostname
- Clarify the default scope comment about backward compatibility
- Add a login example showing --credentials with --hostname

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: scotwells

internal/cmd/auth/login.go

@@ -74,7 +74,11 @@ cannot be derived from the auth hostname (e.g., in self-hosted environments).`,
   datumctl auth login --hostname auth.example.com --client-id 123456789
 
   # Log in to a self-hosted environment with explicit API hostname
-  datumctl auth login --hostname auth.example.com --api-hostname api.example.com --client-id 123456789`,
+  datumctl auth login --hostname auth.example.com --api-hostname api.example.com --client-id 123456789
+
+  # Log in with a machine account credentials file (hostname is required
+  # to tell datumctl which environment to authenticate against)
+  datumctl auth login --credentials ./my-key.json --hostname auth.staging.env.datum.net`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		if credentialsFile != "" {
 			return runMachineAccountLogin(cmd.Context(), credentialsFile, hostname, apiHostname, debugCredentials)

internal/cmd/auth/machine_account_login.go

@@ -14,9 +14,9 @@ import (
 	"go.datum.net/datumctl/internal/keyring"
 )
 
-// defaultMachineAccountScope is the scope string used for machine account token exchanges
-// when the credentials file does not specify one. It mirrors the scopes requested by the
-// interactive login flow.
+// defaultMachineAccountScope is used when the credentials file does not
+// specify a scope. The file's scope field is still honored for backward
+// compatibility; new credentials files should omit it.
 const defaultMachineAccountScope = "openid profile email offline_access"
 
 // runMachineAccountLogin handles the --credentials flag path for `datumctl auth login`.
@@ -55,15 +55,15 @@ func runMachineAccountLogin(ctx context.Context, credentialsPath, hostname, apiH
 		missing = append(missing, "private_key")
 	}
 	if len(missing) > 0 {
-		return fmt.Errorf("credentials file is missing required fields: %v", missing)
+		return fmt.Errorf("credentials file is missing required fields: %s", strings.Join(missing, ", "))
 	}
 
 	// Discover the token endpoint from the OIDC provider's well-known config.
 	// This mirrors the pattern used by the interactive login flow in login.go.
 	providerURL := fmt.Sprintf("https://%s", hostname)
 	provider, err := oidc.NewProvider(ctx, providerURL)
 	if err != nil {
-		return fmt.Errorf("failed to discover OIDC provider at %s: %w", providerURL, err)
+		return fmt.Errorf("failed to discover OIDC provider at %s: %w (pass --hostname to point datumctl at your Datum Cloud auth server)", providerURL, err)
 	}
 	tokenURI := provider.Endpoint().TokenURL