cli: make bundled help self-describing

packages/inbox-runtime/internal/cli/inbox/list.go

@@ -23,6 +23,14 @@ func newListCmd(root *rootOptions) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
 		Short: "List threads with filters",
+		Long: helpLong(
+			"Use list for broad inbox inspection across many threads.",
+			"Compared with fetch: fetch is the worker discovery step before claim, while list is the general inspection surface for leaders, operators, and debugging.",
+			"Use list when you want to scan by assigned worker, creator, or status without implying that the current agent plans to claim the work.",
+		),
+		Example: `  inbox --db .agents/coord.db list --status blocked,in_progress
+  inbox --db .agents/coord.db list --assigned-to worker-a --status pending --limit 10
+  inbox --db .agents/coord.db list --created-by orch --status done,failed`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
@@ -73,11 +81,11 @@ func newListCmd(root *rootOptions) *cobra.Command {
 		},
 	}
 
-	cmd.Flags().StringVar(&opts.agent, "agent", "", "Assigned agent filter shortcut")
-	cmd.Flags().StringVar(&opts.statuses, "status", "", "Comma-separated status filter")
-	cmd.Flags().StringVar(&opts.createdBy, "created-by", "", "Created-by filter")
-	cmd.Flags().StringVar(&opts.assignedTo, "assigned-to", "", "Assigned-to filter")
-	cmd.Flags().IntVar(&opts.limit, "limit", 20, "Maximum number of threads")
+	cmd.Flags().StringVar(&opts.agent, "agent", "", "Shortcut for filtering threads assigned to one agent")
+	cmd.Flags().StringVar(&opts.statuses, "status", "", "Comma-separated status filter such as pending,blocked,done")
+	cmd.Flags().StringVar(&opts.createdBy, "created-by", "", "Only include threads created by this agent")
+	cmd.Flags().StringVar(&opts.assignedTo, "assigned-to", "", "Only include threads currently assigned to this agent")
+	cmd.Flags().IntVar(&opts.limit, "limit", 20, "Maximum number of threads to return")
 
 	return cmd
 }