fix(cli): add comprehensive help text to github run subcommand

Fixes bounty issue #1391

The github run subcommand had minimal help text with no usage examples
or explanation of when/how to use the command. This commit adds:
- Extended description explaining the command runs in GitHub Actions context
- Usage examples showing typical invocation from workflows and local testing
- Documentation of required environment variables (GITHUB_TOKEN, etc.)
- List of supported GitHub events
- References to related commands (github install, github status)
- Environment variable support via clap env attribute for auto-reading

Author: factorydroid

cortex-cli/src/github_cmd.rs

@@ -23,6 +23,13 @@ pub enum GitHubSubcommand {
     Install(InstallArgs),
 
     /// Run GitHub agent in Actions context.
+    ///
+    /// This command is designed to be called from within a GitHub Actions workflow.
+    /// It processes GitHub events (issues, pull requests, comments) and responds
+    /// automatically using the Cortex AI agent.
+    ///
+    /// Typically, you don't run this command manually. Instead, use `cortex github install`
+    /// to set up the workflow that will call this command automatically.
     Run(RunArgs),
 
     /// Check GitHub Actions installation status.
@@ -55,25 +62,61 @@ pub struct InstallArgs {
 
 /// Arguments for run command.
 #[derive(Debug, Parser)]
+#[command(
+    about = "Run GitHub agent in Actions context",
+    long_about = "Run GitHub agent in Actions context.\n\n\
+This command is designed to be called from within a GitHub Actions workflow. \
+It processes GitHub events (issues, pull requests, comments) and responds \
+automatically using the Cortex AI agent.\n\n\
+USAGE:\n\
+  Typically, you don't run this command manually. Use `cortex github install` \
+to set up the workflow that will call this command automatically.\n\n\
+ENVIRONMENT VARIABLES:\n\
+  The following environment variables are automatically set by GitHub Actions:\n\
+    GITHUB_TOKEN        - Token for GitHub API access (required)\n\
+    GITHUB_EVENT_PATH   - Path to the event payload JSON file (required)\n\
+    GITHUB_REPOSITORY   - Repository in owner/repo format (required)\n\
+    GITHUB_RUN_ID       - The workflow run ID (optional)\n\n\
+EXAMPLES:\n\
+  # Typical invocation from a GitHub Actions workflow:\n\
+  cortex github run --event ${{ github.event_name }} \\\n\
+    --token ${{ secrets.GITHUB_TOKEN }} \\\n\
+    --event-path ${{ github.event_path }} \\\n\
+    --repository ${{ github.repository }}\n\n\
+  # Test locally with a dry run:\n\
+  cortex github run --event issue_comment \\\n\
+    --token ghp_xxxx \\\n\
+    --event-path ./event.json \\\n\
+    --repository owner/repo \\\n\
+    --dry-run\n\n\
+SUPPORTED EVENTS:\n\
+  issue_comment       - Triggered on issue or PR comments\n\
+  pull_request        - Triggered on PR open, sync, or reopen\n\
+  pull_request_review - Triggered on PR review submission\n\
+  issues              - Triggered when issues are opened\n\n\
+SEE ALSO:\n\
+  cortex github install  - Install the workflow file\n\
+  cortex github status   - Check installation status"
+)]
 pub struct RunArgs {
     /// GitHub event type.
     #[arg(long, short, value_parser = clap::builder::PossibleValuesParser::new(["issue_comment", "pull_request", "pull_request_review", "issues"]))]
     pub event: String,
 
-    /// GitHub token for API access.
-    #[arg(long, short)]
+    /// GitHub token for API access (or set GITHUB_TOKEN env var).
+    #[arg(long, short, env = "GITHUB_TOKEN")]
     pub token: Option<String>,
 
-    /// Path to the event payload JSON file.
-    #[arg(long)]
+    /// Path to the event payload JSON file (or set GITHUB_EVENT_PATH env var).
+    #[arg(long, env = "GITHUB_EVENT_PATH")]
     pub event_path: Option<PathBuf>,
 
-    /// GitHub repository (owner/repo format).
-    #[arg(long)]
+    /// GitHub repository in owner/repo format (or set GITHUB_REPOSITORY env var).
+    #[arg(long, env = "GITHUB_REPOSITORY")]
     pub repository: Option<String>,
 
-    /// GitHub run ID.
-    #[arg(long)]
+    /// GitHub workflow run ID (or set GITHUB_RUN_ID env var).
+    #[arg(long, env = "GITHUB_RUN_ID")]
     pub run_id: Option<String>,
 
     /// Dry run mode - don't execute, just show what would happen.