cli: make bundled help self-describing

packages/orch-runtime/internal/cli/orch/run.go

@@ -23,6 +23,12 @@ func newRunCmd(root *rootOptions) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "run",
 		Short: "Run management commands",
+		Long: helpLong(
+			"Use run commands to create or inspect one orchestration run.",
+			"A run is the durable container for tasks, dependencies, attempts, and events for one user request or project slice.",
+		),
+		Example: `  orch --db .agents/coord.db run init --run blog_mvp_001 --goal "Build blog MVP"
+  orch --db .agents/coord.db run show --run blog_mvp_001`,
 	}
 
 	cmd.AddCommand(newRunInitCmd(root))
@@ -37,6 +43,12 @@ func newRunInitCmd(root *rootOptions) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "init",
 		Short: "Create a new orchestration run",
+		Long: helpLong(
+			"Use run init to create one durable run that will own tasks, dependencies, attempts, and events for a single user request or project slice.",
+			"run IDs should be stable within the database path and are later reused by every other orch command.",
+			"Create the run before adding tasks, dependencies, or dispatching work.",
+		),
+		Example: `  orch --db .agents/coord.db run init --run blog_mvp_001 --goal "Build blog MVP" --summary "Public blog plus admin CRUD"`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 
@@ -86,6 +98,11 @@ func newRunShowCmd(root *rootOptions) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "show",
 		Short: "Show run metadata and aggregate state",
+		Long: helpLong(
+			"Use run show to inspect the lightweight run view with run metadata and aggregate task counts.",
+			"Prefer status when you need the full task list and latest attempt/message context.",
+		),
+		Example: `  orch --db .agents/coord.db run show --run blog_mvp_001`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()