cmd: fix help text and examples (#40)

## Description

Fixes help text issues identified in internal testing. No code logic changes — text updates, codegen example fixes, and help improvements.

**Examples fixed:**
- `video create`: replaced non-existent `--avatar-id --script --voice-id` with realistic `--data` JSON
- `video-agent create`: removed non-existent `--style-id`, added `--data` alternative alongside `--prompt`
- `video-translate create`: added `--output-languages` flag example (existing flag, was missing from examples)
- `video-agent sessions resources`: fixed verb from `list` to `get` (singleton endpoint)

**Help text improvements:**
- `--data` flag now documents merge behavior: "When used with individual flags, flags override matching fields in the JSON."
- Root `--help` shows exit codes (0=success, 1=general, 2=usage, 3=auth)
- `completion` command hidden from top-level help via `CompletionOptions.HiddenDefaultCmd`

**Group descriptions:**
- `voice`: "Text-to-speech and voice management" → "Create speech audio and manage voices"
- `webhook`: "Manage webhook endpoints and events" → "Create, list, and manage webhook endpoints and events"
- Implemented via `descriptionOverrides` map in `codegen/grouper.go`

Stacked on PR #39 (spinner).

## Testing

1 new test: `TestGeneratedRoot_Help_ShowsExitCodesAndHidesCompletion` — verifies exit codes in help output and completion command hidden.

Generated files regenerated with `make generate`. Golden files unchanged (examples are not in golden test spec).

Author: somanshreddy

cmd/heygen/builder.go

@@ -147,7 +147,7 @@ func buildCobraCommand(spec *command.Spec, ctx *cmdContext) *cobra.Command {
 	// Add -d/--data for commands with JSON request bodies
 	if spec.BodyEncoding == "json" {
 		cmd.Flags().StringVarP(&rawData, "data", "d", "",
-			"JSON request body (inline JSON, file path, or - for stdin)")
+			"JSON request body (inline JSON, file path, or - for stdin). When used with individual flags, flags override matching fields in the JSON.")
 	}
 
 	return cmd

cmd/heygen/generated_root_test.go

@@ -130,6 +130,23 @@ func TestGeneratedRoot_IntermediateHelp(t *testing.T) {
 	}
 }
 
+func TestGeneratedRoot_Help_ShowsExitCodesAndHidesCompletion(t *testing.T) {
+	srv := setupTestServer(t, map[string]testHandler{})
+	defer srv.Close()
+
+	res := runCommand(t, srv.URL, "test-key", "--help")
+
+	if res.ExitCode != 0 {
+		t.Errorf("ExitCode = %d, want 0\nstderr: %s", res.ExitCode, res.Stderr)
+	}
+	if !strings.Contains(res.Stdout, "Exit Codes:") || !strings.Contains(res.Stdout, "3   Authentication error") {
+		t.Errorf("root help missing documented exit codes\nstdout: %s", res.Stdout)
+	}
+	if strings.Contains(res.Stdout, "completion") {
+		t.Errorf("root help should hide completion command\nstdout: %s", res.Stdout)
+	}
+}
+
 func TestGeneratedRoot_VideoAgentHelp_FlattensNestedLeaves(t *testing.T) {
 	srv := setupTestServer(t, map[string]testHandler{})
 	defer srv.Close()

cmd/heygen/root.go

@@ -46,6 +46,7 @@ Exit Codes:
 	root.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
 		return clierrors.NewUsage(err.Error())
 	})
+	root.CompletionOptions.HiddenDefaultCmd = true
 	root.PersistentFlags().Bool("human", false, "Display output as a formatted table instead of JSON")
 
 	root.AddCommand(newAuthCmd(ctx))
@@ -77,6 +78,7 @@ func newRootCmdWithSpecs(version string, formatter output.Formatter, groups map[
 	root.SetFlagErrorFunc(func(cmd *cobra.Command, err error) error {
 		return clierrors.NewUsage(err.Error())
 	})
+	root.CompletionOptions.HiddenDefaultCmd = true
 	root.PersistentFlags().Bool("human", false, "Display output as a formatted table instead of JSON")
 
 	root.AddCommand(newAuthCmd(ctx))

codegen/examples/video-agent.yaml

@@ -1,5 +1,6 @@
 "POST /v3/video-agents":
-  - "heygen video-agent create --prompt 'Make a product demo' --style-id modern"
+  - "heygen video-agent create --prompt 'Make a product demo'"
+  - "heygen video-agent create -d '{\"prompt\":\"Make a product demo\"}'"
 "GET /v3/video-agents/styles":
   - "heygen video-agent styles list"
 "POST /v3/video-agents/sessions":
@@ -9,6 +10,6 @@
 "POST /v3/video-agents/sessions/{session_id}/messages":
   - "heygen video-agent sessions messages create <session-id> --message 'Add intro'"
 "GET /v3/video-agents/sessions/{session_id}/resources":
-  - "heygen video-agent sessions resources list <session-id>"
+  - "heygen video-agent sessions resources get <session-id>"
 "POST /v3/video-agents/sessions/{session_id}/stop":
   - "heygen video-agent sessions stop <session-id>"

codegen/examples/video-translate.yaml

@@ -4,6 +4,7 @@
   - "heygen video-translate get <video-translation-id>"
 "POST /v3/video-translations":
   - "cat request.json | heygen video-translate create -d -"
+  - "heygen video-translate create --output-languages es --mode precision"
 "PATCH /v3/video-translations/{video_translation_id}":
   - "heygen video-translate update <video-translation-id> --title 'New title'"
 "DELETE /v3/video-translations/{video_translation_id}":

codegen/examples/video.yaml

@@ -2,7 +2,7 @@
   - "heygen video list --limit 10"
   - "heygen video list --folder-id abc123"
 "POST /v3/videos":
-  - "heygen video create --avatar-id josh_lite --script 'Hello world' --voice-id en_male"
+  - "heygen video create -d '{\"video_inputs\":[{\"character\":{\"type\":\"avatar\",\"avatar_id\":\"josh_lite\"},\"voice\":{\"type\":\"text\",\"voice_id\":\"en_male\",\"input_text\":\"Hello world\"}}]}'"
 "GET /v3/videos/{video_id}":
   - "heygen video get <video-id>"
 "DELETE /v3/videos/{video_id}":

codegen/grouper.go

@@ -58,13 +58,22 @@ import (
 // Used by the builder for group command help text.
 type GroupDescriptions map[string]string
 
+var descriptionOverrides = GroupDescriptions{
+	"voice":   "Create speech audio and manage voices",
+	"webhook": "Create, list, and manage webhook endpoints and events",
+}
+
 func GroupEndpoints(doc *openapi3.T, examples Examples) (command.Groups, GroupDescriptions, error) {
 	groups := make(command.Groups)
 	descriptions := make(GroupDescriptions)
 
 	// Collect tag descriptions from the spec's top-level tags array
 	for _, tag := range doc.Tags {
 		groupName := deriveGroupName(tag.Name)
+		if override, ok := descriptionOverrides[groupName]; ok {
+			descriptions[groupName] = override
+			continue
+		}
 		if tag.Description != "" {
 			descriptions[groupName] = tag.Description
 		}