docs: explain root error handler behavior

Made-with: Cursor

Author: rgarcia

cmd/root.go

@@ -205,13 +205,21 @@ func Execute(m Metadata) {
 		fang.WithCommit(metadata.Commit),
 		fang.WithErrorHandler(func(w io.Writer, styles fang.Styles, err error) {
 			err = util.CleanedUpSdkError{Err: err}
+
+			// Some subcommands intentionally suppress diagnostics for curl-like
+			// quiet modes while still returning a non-zero exit status.
 			var silent interface{ Silent() bool }
 			if errors.As(err, &silent) && silent.Silent() {
 				return
 			}
+
 			// remove margins so that it matches other pterm.error "style"
 			// we should add them back later as it looks cleaner
 			errorTextStyle := styles.ErrorText.UnsetMargins()
+
+			// Fang passes the destination for errors (normally stderr). pterm's
+			// global Error printer does not know about it, so temporarily point
+			// pterm at fang's writer for this handler invocation.
 			oldErrorWriter := pterm.Error.Writer
 			pterm.Error.Writer = w
 			defer func() {