fix(cli): address review findings — conflict detection, polish

- team get: error when positional <id> and any named flag are both provided
  (previously silently discarded the flag); add test for the conflict case
- Restore member-resolution comment explaining the second round-trip
- insight Short: trim to 63 chars (was 104, longest in codebase)
- incident list Long: use <team|responder|channel> metavar instead of
  bare pipe to avoid shell-alternation confusion

Author: ysyneu

internal/cli/incident.go

@@ -80,7 +80,7 @@ func newIncidentListCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List incidents",
-		Long:  curatedLong("List incidents matching the given filters. The --since/--until window must be < 31 days; --limit max is 100.\n\nSee also: fduty insight team|responder|channel for aggregated metrics (MTTA, MTTR, noise reduction) instead of paginating raw incidents.", "Incidents", "List"),
+		Long:  curatedLong("List incidents matching the given filters. The --since/--until window must be < 31 days; --limit max is 100.\n\nSee also: fduty insight <team|responder|channel> for aggregated metrics (MTTA, MTTR, noise reduction) instead of paginating raw incidents.", "Incidents", "List"),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return runCommand(cmd, args, func(ctx *RunContext) error {
 				startTime, err := timeutil.Parse(since)

internal/cli/insight.go

@@ -13,7 +13,7 @@ import (
 func newInsightCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "insight",
-		Short: "Query aggregated incident metrics by team/responder/channel (preferred over incident list for analytics)",
+		Short: "Query aggregated incident metrics by team, responder, or channel",
 	}
 	// insight team/channel/responder are now served by the generated commands
 	// (richer flag set: severities, *_ids, fields, aggregate-unit, …; relative

internal/cli/team.go

@@ -108,6 +108,11 @@ Examples:
 		Args: optionalArg("id"),
 		PreRunE: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 1 {
+				for _, f := range []string{"id", "name", "ref-id"} {
+					if cmd.Flags().Changed(f) {
+						return fmt.Errorf("positional <id> cannot be combined with --%s", f)
+					}
+				}
 				return nil
 			}
 			return requireExactlyOneFlag(cmd, "id", "name", "ref-id")
@@ -134,6 +139,8 @@ Examples:
 					return ctx.Printer.Print(team, nil)
 				}
 
+				// TeamItem carries only member person IDs; resolve names/emails
+				// in one batch to replicate the legacy member display.
 				members := resolveTeamMemberInfos(ctx, team.PersonIDs)
 				printTeamDetail(ctx.Writer, team, members)
 				return nil

internal/cli/team_get_test.go

@@ -27,3 +27,12 @@ func TestTeamGetPositionalArgBypassesPreRunE(t *testing.T) {
 		t.Fatalf("PreRunE should succeed with positional arg, got: %v", err)
 	}
 }
+
+func TestTeamGetPositionalAndFlagConflictFails(t *testing.T) {
+	cmd := newTeamGetCmd()
+	_ = cmd.Flags().Set("id", "456")
+	err := cmd.PreRunE(cmd, []string{"123"})
+	if err == nil {
+		t.Fatal("expected error when positional arg and --id flag are both provided")
+	}
+}