Merge pull request #982 from zeroclaw-labs/fix/cli-help-text-improvements

docs(cli): add detailed help text and examples to complex subcommands

src/main.rs

@@ -138,6 +138,17 @@ enum Commands {
     },
 
     /// Start the AI agent loop
+    #[command(long_about = "\
+Start the AI agent loop.
+
+Launches an interactive chat session with the configured AI provider. \
+Use --message for single-shot queries without entering interactive mode.
+
+Examples:
+  zeroclaw agent                              # interactive session
+  zeroclaw agent -m \"Summarize today's logs\"  # single message
+  zeroclaw agent -p anthropic --model claude-sonnet-4-20250514
+  zeroclaw agent --peripheral nucleo-f401re:/dev/ttyACM0")]
     Agent {
         /// Single message mode (don't enter interactive mode)
         #[arg(short, long)]
@@ -161,6 +172,18 @@ enum Commands {
     },
 
     /// Start the gateway server (webhooks, websockets)
+    #[command(long_about = "\
+Start the gateway server (webhooks, websockets).
+
+Runs the HTTP/WebSocket gateway that accepts incoming webhook events \
+and WebSocket connections. Bind address defaults to the values in \
+your config file (gateway.host / gateway.port).
+
+Examples:
+  zeroclaw gateway                  # use config defaults
+  zeroclaw gateway -p 8080          # listen on port 8080
+  zeroclaw gateway --host 0.0.0.0   # bind to all interfaces
+  zeroclaw gateway -p 0             # random available port")]
     Gateway {
         /// Port to listen on (use 0 for random available port); defaults to config gateway.port
         #[arg(short, long)]
@@ -172,6 +195,21 @@ enum Commands {
     },
 
     /// Start long-running autonomous runtime (gateway + channels + heartbeat + scheduler)
+    #[command(long_about = "\
+Start the long-running autonomous daemon.
+
+Launches the full ZeroClaw runtime: gateway server, all configured \
+channels (Telegram, Discord, Slack, etc.), heartbeat monitor, and \
+the cron scheduler. This is the recommended way to run ZeroClaw in \
+production or as an always-on assistant.
+
+Use 'zeroclaw service install' to register the daemon as an OS \
+service (systemd/launchd) for auto-start on boot.
+
+Examples:
+  zeroclaw daemon                   # use config defaults
+  zeroclaw daemon -p 9090           # gateway on port 9090
+  zeroclaw daemon --host 127.0.0.1  # localhost only")]
     Daemon {
         /// Port to listen on (use 0 for random available port); defaults to config gateway.port
         #[arg(short, long)]
@@ -198,6 +236,25 @@ enum Commands {
     Status,
 
     /// Configure and manage scheduled tasks
+    #[command(long_about = "\
+Configure and manage scheduled tasks.
+
+Schedule recurring, one-shot, or interval-based tasks using cron \
+expressions, RFC 3339 timestamps, durations, or fixed intervals.
+
+Cron expressions use the standard 5-field format: \
+'min hour day month weekday'. Timezones default to UTC; \
+override with --tz and an IANA timezone name.
+
+Examples:
+  zeroclaw cron list
+  zeroclaw cron add '0 9 * * 1-5' 'Good morning' --tz America/New_York
+  zeroclaw cron add '*/30 * * * *' 'Check system health'
+  zeroclaw cron add-at 2025-01-15T14:00:00Z 'Send reminder'
+  zeroclaw cron add-every 60000 'Ping heartbeat'
+  zeroclaw cron once 30m 'Run backup in 30 minutes'
+  zeroclaw cron pause <task-id>
+  zeroclaw cron update <task-id> --expression '0 8 * * *' --tz Europe/London")]
     Cron {
         #[command(subcommand)]
         cron_command: CronCommands,
@@ -213,6 +270,19 @@ enum Commands {
     Providers,
 
     /// Manage channels (telegram, discord, slack)
+    #[command(long_about = "\
+Manage communication channels.
+
+Add, remove, list, and health-check channels that connect ZeroClaw \
+to messaging platforms. Supported channel types: telegram, discord, \
+slack, whatsapp, matrix, imessage, email.
+
+Examples:
+  zeroclaw channel list
+  zeroclaw channel doctor
+  zeroclaw channel add telegram '{\"bot_token\":\"...\",\"name\":\"my-bot\"}'
+  zeroclaw channel remove my-bot
+  zeroclaw channel bind-telegram zeroclaw_user")]
     Channel {
         #[command(subcommand)]
         channel_command: ChannelCommands,
@@ -243,18 +313,52 @@ enum Commands {
     },
 
     /// Discover and introspect USB hardware
+    #[command(long_about = "\
+Discover and introspect USB hardware.
+
+Enumerate connected USB devices, identify known development boards \
+(STM32 Nucleo, Arduino, ESP32), and retrieve chip information via \
+probe-rs / ST-Link.
+
+Examples:
+  zeroclaw hardware discover
+  zeroclaw hardware introspect /dev/ttyACM0
+  zeroclaw hardware info --chip STM32F401RETx")]
     Hardware {
         #[command(subcommand)]
         hardware_command: zeroclaw::HardwareCommands,
     },
 
     /// Manage hardware peripherals (STM32, RPi GPIO, etc.)
+    #[command(long_about = "\
+Manage hardware peripherals.
+
+Add, list, flash, and configure hardware boards that expose tools \
+to the agent (GPIO, sensors, actuators). Supported boards: \
+nucleo-f401re, rpi-gpio, esp32, arduino-uno.
+
+Examples:
+  zeroclaw peripheral list
+  zeroclaw peripheral add nucleo-f401re /dev/ttyACM0
+  zeroclaw peripheral add rpi-gpio native
+  zeroclaw peripheral flash --port /dev/cu.usbmodem12345
+  zeroclaw peripheral flash-nucleo")]
     Peripheral {
         #[command(subcommand)]
         peripheral_command: zeroclaw::PeripheralCommands,
     },
 
     /// Manage configuration
+    #[command(long_about = "\
+Manage ZeroClaw configuration.
+
+Inspect and export configuration settings. Use 'schema' to dump \
+the full JSON Schema for the config file, which documents every \
+available key, type, and default value.
+
+Examples:
+  zeroclaw config schema              # print JSON Schema to stdout
+  zeroclaw config schema > schema.json")]
     Config {
         #[command(subcommand)]
         config_command: ConfigCommands,