From b9ae2bd050780e8b02be8d676ddb00cfdfe1922b Mon Sep 17 00:00:00 2001
From: Bortlesboat <bortstheboat@gmail.com>
Date: Tue, 12 May 2026 15:08:23 -0400
Subject: [PATCH] docs: clarify utility help syntax

---
 src/cortex-cli/src/cli/styles.rs            |  1 +
 src/cortex-cli/tests/utilities_help_note.rs | 12 ++++++++++++
 2 files changed, 13 insertions(+)
 create mode 100644 src/cortex-cli/tests/utilities_help_note.rs

diff --git a/src/cortex-cli/src/cli/styles.rs b/src/cortex-cli/src/cli/styles.rs
index 4032f94e7..c352784a1 100644
--- a/src/cortex-cli/src/cli/styles.rs
+++ b/src/cortex-cli/src/cli/styles.rs
@@ -119,6 +119,7 @@ pub const HELP_TEMPLATE: &str = color_print::cstr!(
     <green,bold>scrape</>      Scrape web content to markdown/text/html
     <green,bold>stats</>       Show usage statistics
     <green,bold>completion</>  Generate shell completion scripts
+    <dim>Note: Commands without subcommands only support --help; nested commands like github also accept help.</>
 
 <cyan,bold>🔧 Maintenance:</>
     <green,bold>upgrade</>     Check for and install updates
diff --git a/src/cortex-cli/tests/utilities_help_note.rs b/src/cortex-cli/tests/utilities_help_note.rs
new file mode 100644
index 000000000..e72a72de9
--- /dev/null
+++ b/src/cortex-cli/tests/utilities_help_note.rs
@@ -0,0 +1,12 @@
+use clap::CommandFactory;
+use cortex_cli::cli::Cli;
+
+#[test]
+fn root_help_documents_utility_help_syntax_split() {
+    let help = Cli::command().render_long_help().to_string();
+
+    assert!(
+        help.contains("Commands without subcommands only support --help"),
+        "root help should explain why `cortex github help` works while single-purpose utilities use `--help`:\n{help}"
+    );
+}