feat(sheets): drop pre-refactor aliases from sheets --help listing

The refactored + commands have been the default for over a month. Hide the
deprecated pre-refactor aliases from `sheets --help` via a custom cobra
usage template that skips the deprecated group. Aliases stay registered
and executable: their own `sheets <alias> --help` still shows the
(→ +new-command) pointer, unknown-subcommand suggestions still span them,
and execution still returns the _notice.

shortcuts/register.go

@@ -205,16 +205,18 @@ func installBrandRestrictionGuard(svc *cobra.Command, service string, brand core
 	svc.Long = fmt.Sprintf("The %q feature is not yet supported on the %s brand.", service, brand)
 }
 
-// Sheets backward-compatibility help grouping.
+// Sheets backward-compatibility grouping.
 //
 // shortcuts/sheets/backward keeps the pre-refactor command names alive so that
 // users whose lark-sheets skill predates the refactor keep working even after
-// upgrading only the binary. In `sheets --help` those aliases would otherwise
-// sort alphabetically into the same flat list as the current commands,
-// indistinguishable from them. applySheetsCompatGroups splits them into a
-// dedicated cobra group whose heading tells the user to update their skill, and
-// appends a "(→ +new-command)" pointer to each alias so the migration target is
-// obvious. Pure presentation — the aliases stay fully executable.
+// upgrading only the binary. applySheetsCompatGroups tags each alias into a
+// dedicated deprecated cobra group. The refactored commands have been the
+// default for over a month, so `sheets --help` no longer lists these aliases:
+// sheetsUsageTemplate renders every group except the deprecated one. The
+// grouping is still applied for two reasons — the unknown-subcommand path
+// (cmd/root.go) keys off it to classify a mistyped legacy alias, and each
+// alias's own `sheets <alias> --help` still surfaces the "(→ +new-command)"
+// migration pointer appended below. The aliases stay fully executable.
 const (
 	sheetsCurrentGroupID = "sheets-current"
 	// sheetsDeprecatedGroupID aliases the shared deprecated-group id so both
@@ -224,9 +226,10 @@ const (
 )
 
 // sheetsAliasReplacement maps each pre-refactor sheets alias to the current
-// command(s) that replace it, shown as a "(→ ...)" suffix in --help. Aliases
-// absent from this map still land in the deprecated group, just without a
-// pointer, so a missing entry degrades gracefully rather than misgrouping.
+// command(s) that replace it, shown as a "(→ ...)" suffix in the alias's own
+// --help and reused by wrapSheetsBackwardDeprecation for the on-execution
+// _notice. Aliases absent from this map still land in the deprecated group,
+// just without a pointer, so a missing entry degrades gracefully.
 var sheetsAliasReplacement = map[string]string{
 	// spreadsheet / sheet management
 	"+create":       "+workbook-create",
@@ -279,6 +282,43 @@ var sheetsAliasReplacement = map[string]string{
 	"+delete-float-image": "+float-image-delete",
 }
 
+// sheetsUsageTemplate is cobra v1.10.2's stock usage template with a single
+// change: the group loop is guarded by {{if ne $group.ID "deprecated"}} so the
+// deprecated pre-refactor aliases are omitted from `sheets --help` altogether.
+// Everything else — current commands, ungrouped metaapi subcommands under
+// "Additional Commands", flags — renders exactly as cobra's default. Keep in
+// sync with cobra's defaultUsageTemplate on upgrade.
+var sheetsUsageTemplate = fmt.Sprintf(`Usage:{{if .Runnable}}
+  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}
+  {{.CommandPath}} [command]{{end}}{{if gt (len .Aliases) 0}}
+
+Aliases:
+  {{.NameAndAliases}}{{end}}{{if .HasExample}}
+
+Examples:
+{{.Example}}{{end}}{{if .HasAvailableSubCommands}}{{$cmds := .Commands}}{{if eq (len .Groups) 0}}
+
+Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{else}}{{range $group := .Groups}}{{if ne $group.ID %q}}
+
+{{.Title}}{{range $cmds}}{{if (and (eq .GroupID $group.ID) (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}}
+
+Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
+
+Flags:
+{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
+
+Global Flags:
+{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
+
+Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
+  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
+
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}
+`, sheetsDeprecatedGroupID)
+
 func applySheetsCompatGroups(svc *cobra.Command) {
 	svc.AddGroup(
 		&cobra.Group{ID: sheetsCurrentGroupID, Title: "Available Commands:"},
@@ -310,6 +350,11 @@ func applySheetsCompatGroups(svc *cobra.Command) {
 			c.GroupID = sheetsCurrentGroupID
 		}
 	}
+
+	// Refactored commands have been the default for over a month: drop the
+	// deprecated group from `sheets --help` (see sheetsUsageTemplate). The
+	// aliases remain grouped and executable, just no longer advertised here.
+	svc.SetUsageTemplate(sheetsUsageTemplate)
 }
 
 // wrapSheetsBackwardDeprecation decorates each backward-compatibility sheets

shortcuts/register_test.go

@@ -511,10 +511,11 @@ func TestApplySheetsCompatGroups(t *testing.T) {
 	}
 }
 
-// End-to-end: the rendered `sheets --help` must surface the deprecated-group
-// heading (telling users to update their skill) plus the per-alias migration
-// pointers, while keeping the refactored shortcuts under Available Commands.
-func TestRegisterShortcutsSheetsHelpGroupsDeprecatedAliases(t *testing.T) {
+// End-to-end: `sheets --help` must list refactored shortcuts under Available
+// Commands, but no longer advertise the deprecated pre-refactor aliases or the
+// deprecated group heading (sheetsUsageTemplate skips that group). The aliases
+// stay registered and executable — hidden from the parent listing, not removed.
+func TestRegisterShortcutsSheetsHelpHidesDeprecatedAliases(t *testing.T) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))
 
@@ -530,19 +531,25 @@ func TestRegisterShortcutsSheetsHelpGroupsDeprecatedAliases(t *testing.T) {
 	}
 	got := out.String()
 
-	for _, want := range []string{
-		"Available Commands:",
-		"Deprecated pre-refactor commands",
-		"update your lark-sheets skill",
-		"+read",
-		"(→ +cells-get)",
-		"+write",
-		"(→ +cells-set)",
-	} {
+	for _, want := range []string{"Available Commands:", "+cells-get"} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("sheets help missing %q:\n%s", want, got)
 		}
 	}
+	for _, unwanted := range []string{
+		"Deprecated pre-refactor commands",
+		"update your lark-sheets skill",
+		"+read",
+		"+write",
+	} {
+		if strings.Contains(got, unwanted) {
+			t.Fatalf("sheets help still shows deprecated content %q:\n%s", unwanted, got)
+		}
+	}
+
+	if alias, _, ferr := sheetsCmd.Find([]string{"+read"}); ferr != nil || alias == nil {
+		t.Fatalf("deprecated alias +read should stay registered, got err=%v cmd=%v", ferr, alias)
+	}
 }
 
 // wrapSheetsBackwardDeprecation must decorate each alias's Execute so that