From 1af1a5b86f642ae7b053037bc472913cfbc1e206 Mon Sep 17 00:00:00 2001
From: Ogulcan Celik <ogulcancelik@gmail.com>
Date: Fri, 14 Aug 2026 04:22:48 +0300
Subject: feat(cli): guide agents to Herdr resources

---
 src/cli.rs      |  9 +++++++++
 src/cli/spec.rs | 30 ++++++++++++++++++++++++++----
 src/main.rs     |  3 ++-
 3 files changed, 37 insertions(+), 5 deletions(-)

(limited to 'src')

diff --git a/src/cli.rs b/src/cli.rs
index 6acbfcbe..7f813eb7 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -29,6 +29,15 @@ const TERMINAL_SESSION_OBSERVE_USAGE: &str =
     "usage: herdr terminal session observe <target> [--cols N] [--rows N]";
 const TERMINAL_SESSION_CONTROL_USAGE: &str =
     "usage: herdr terminal session control <target> [--takeover] [--cols N] [--rows N]";
+pub(crate) const AGENT_HELP_FOOTER: &str = concat!(
+    "Are you an AI? Use these resources ONLY IF your task specifically asks you to:\n",
+    "  Help a human understand or set up Herdr for the first time:\n",
+    "    https://herdr.dev/agent-guide.md\n",
+    "  Debug or investigate a problem with Herdr:\n",
+    "    https://herdr.dev/llms.txt\n",
+    "  Control Herdr panes, agents, or workspaces:\n",
+    "    SKIP if a Herdr skill is already in your context. Otherwise run: herdr --skill",
+);
 
 pub(crate) fn parse_token_assignment(raw: &str) -> Result<(String, Option<String>), String> {
     let Some((key, value)) = raw.split_once('=') else {
diff --git a/src/cli/spec.rs b/src/cli/spec.rs
index ba454bfc..b2b6cb03 100644
--- a/src/cli/spec.rs
+++ b/src/cli/spec.rs
@@ -43,18 +43,23 @@ pub(super) fn command() -> Command {
         .subcommand(session_command())
         .subcommand(integration_command())
         .subcommand(plugin_command());
-    configure_help(command, true)
+    configure_help(command, 0)
 }
 
-fn configure_help(command: Command, root: bool) -> Command {
-    let command = if root {
+fn configure_help(command: Command, depth: usize) -> Command {
+    let command = if depth == 0 {
         command
     } else {
         command.disable_help_flag(false)
     };
+    let command = if depth == 1 && command.has_subcommands() {
+        command.after_help(super::AGENT_HELP_FOOTER)
+    } else {
+        command
+    };
     command
         .disable_help_subcommand(true)
-        .mut_subcommands(|subcommand| configure_help(subcommand, false))
+        .mut_subcommands(|subcommand| configure_help(subcommand, depth + 1))
 }
 
 pub(super) fn print_requested_help(args: &[String]) -> std::io::Result<bool> {
@@ -1306,6 +1311,23 @@ mod tests {
         String::from_utf8(output).unwrap()
     }
 
+    #[test]
+    fn agent_resources_appear_on_command_groups_but_not_leaf_commands() {
+        for group in ["agent", "pane", "workspace", "terminal"] {
+            let help = long_help(&[group]);
+            assert!(
+                help.contains(super::super::AGENT_HELP_FOOTER),
+                "herdr {group} is missing agent resources: {help}"
+            );
+        }
+
+        let leaf = long_help(&["agent", "wait"]);
+        assert!(
+            !leaf.contains(super::super::AGENT_HELP_FOOTER),
+            "leaf help should stay focused: {leaf}"
+        );
+    }
+
     #[test]
     fn next_step_hints_render_without_replacing_existing_after_help() {
         let agent_start = long_help(&["agent", "start"]);
diff --git a/src/main.rs b/src/main.rs
index d3b72192..868c0b5d 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -715,7 +715,8 @@ fn main() -> io::Result<()> {
         println!("Logs:   {}", logging::help_log_paths_summary());
         println!("Env:    HERDR_CONFIG_PATH overrides config file path");
         println!("Home:   https://herdr.dev");
-        println!("Skill:  herdr --skill prints agent instructions for driving herdr from a pane");
+        println!();
+        println!("{}", cli::AGENT_HELP_FOOTER);
         return Ok(());
     }
 
-- 
cgit v1.2.3