cli: make bundled help self-describing

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

@@ -23,6 +23,13 @@ func newWatchCmd(root *rootOptions) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "watch",
 		Short: "Block until new matching activity appears",
+		Long: helpLong(
+			"Use watch to wait for new matching thread activity across the inbox.",
+			"This is useful for operator-style inspection or lightweight agents that need to observe when new work, blocked work, or terminal results appear without polling manually.",
+			"watch is broader than wait-reply: it watches many matching threads, while wait-reply is the worker-side primitive for one blocked thread.",
+		),
+		Example: `  inbox --db .agents/coord.db watch --status pending,blocked
+  inbox --db .agents/coord.db watch --agent worker-a --status pending --after-event 100 --timeout-seconds 300`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
@@ -81,10 +88,10 @@ func newWatchCmd(root *rootOptions) *cobra.Command {
 		},
 	}
 
-	cmd.Flags().StringVar(&opts.agent, "agent", "", "Assigned agent filter")
-	cmd.Flags().StringVar(&opts.statuses, "status", "pending,blocked,done,failed", "Comma-separated status filter")
-	cmd.Flags().IntVar(&opts.timeoutSeconds, "timeout-seconds", 0, "Maximum time to wait; 0 waits forever")
-	cmd.Flags().Int64Var(&opts.afterEventID, "after-event", 0, "Resume after a known event ID")
+	cmd.Flags().StringVar(&opts.agent, "agent", "", "Only wake for threads assigned to this agent")
+	cmd.Flags().StringVar(&opts.statuses, "status", "pending,blocked,done,failed", "Comma-separated thread status filter")
+	cmd.Flags().IntVar(&opts.timeoutSeconds, "timeout-seconds", 0, "Maximum time to wait; 0 means wait forever")
+	cmd.Flags().Int64Var(&opts.afterEventID, "after-event", 0, "Resume after a known inbox event ID")
 
 	return cmd
 }