docs: update AGENTS.md, README.md, and messaging.md to include interactive setup for messaging platforms

Enhanced documentation to reflect the new interactive setup command for configuring messaging platforms (Telegram, Discord, Slack, WhatsApp). Updated sections in AGENTS.md, README.md, and messaging.md to provide clear instructions on using the 'hermes gateway setup' command, improving user experience and accessibility for platform configuration.
2026-03-03 19:00:09 -08:00
parent fa3d7b3d03
commit 1754bdf1e8
3 changed files with 58 additions and 30 deletions
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -235,6 +235,7 @@ The unified `hermes` command provides all functionality:
 | `hermes update` | Update to latest (checks for new config) |
 | `hermes uninstall` | Uninstall (can keep configs for reinstall) |
 | `hermes gateway` | Start gateway (messaging + cron scheduler) |
+| `hermes gateway setup` | Configure messaging platforms interactively |
 | `hermes gateway install` | Install gateway as system service |
 | `hermes cron list` | View scheduled jobs |
 | `hermes cron status` | Check if cron scheduler is running |
@@ -245,7 +246,19 @@ The unified `hermes` command provides all functionality:

 ## Messaging Gateway

-The gateway connects Hermes to Telegram, Discord, and WhatsApp.
+The gateway connects Hermes to Telegram, Discord, Slack, and WhatsApp.
+
+### Setup
+
+The interactive setup wizard handles platform configuration:
+
+```bash
+hermes gateway setup      # Arrow-key menu of all platforms, configure tokens/allowlists/home channels
+```
+
+This is the recommended way to configure messaging. It shows which platforms are already set up, walks through each one interactively, and offers to start/restart the gateway service at the end.
+
+Platforms can also be configured manually in `~/.hermes/.env`:

 ### Configuration (in `~/.hermes/.env`):

--- a/README.md
+++ b/README.md
@@ -220,26 +220,36 @@ See [OpenRouter provider routing docs](https://openrouter.ai/docs/guides/routing

 Chat with Hermes from Telegram, Discord, Slack, or WhatsApp. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.

-### Starting the Gateway
+### Setting Up Messaging Platforms
+
+The easiest way to configure messaging platforms is the interactive setup wizard:
+
+```bash
+hermes gateway setup        # Interactive setup for all messaging platforms
+```
+
+This walks you through configuring each platform with arrow-key selection, shows which platforms are already configured, and offers to start/restart the gateway service when you're done.
+
+You can also configure platforms manually by editing `~/.hermes/.env` directly (see platform-specific details below).
+
+### Gateway Commands

 ```bash
 hermes gateway              # Run in foreground
-hermes gateway install      # Install as systemd service (Linux)
-hermes gateway start        # Start the systemd service
-hermes gateway stop         # Stop the systemd service
+hermes gateway setup        # Configure messaging platforms interactively
+hermes gateway install      # Install as systemd service (Linux) / launchd (macOS)
+hermes gateway start        # Start the service
+hermes gateway stop         # Stop the service
 hermes gateway status       # Check service status
 ```

-The installer will offer to set this up automatically if it detects a bot token.
-
 ### Telegram Setup

 1. **Create a bot:** Message [@BotFather](https://t.me/BotFather) on Telegram, use `/newbot`
 2. **Get your user ID:** Message [@userinfobot](https://t.me/userinfobot) — it replies with your numeric ID
-3. **Configure:**
+3. **Configure:** Run `hermes gateway setup` and select Telegram, or add to `~/.hermes/.env` manually:

 ```bash
-# Add to ~/.hermes/.env:
 TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
 TELEGRAM_ALLOWED_USERS=YOUR_USER_ID    # Comma-separated for multiple users
 ```
@@ -252,10 +262,9 @@ TELEGRAM_ALLOWED_USERS=YOUR_USER_ID    # Comma-separated for multiple users
 2. **Enable intents:** Bot → Privileged Gateway Intents → enable Message Content Intent
 3. **Get your user ID:** Enable Developer Mode in Discord settings, right-click your name → Copy ID
 4. **Invite to your server:** OAuth2 → URL Generator → scopes: `bot`, `applications.commands` → permissions: Send Messages, Read Message History, Attach Files
-5. **Configure:**
+5. **Configure:** Run `hermes gateway setup` and select Discord, or add to `~/.hermes/.env` manually:

 ```bash
-# Add to ~/.hermes/.env:
 DISCORD_BOT_TOKEN=MTIz...
 DISCORD_ALLOWED_USERS=YOUR_USER_ID
 ```
@@ -267,10 +276,9 @@ DISCORD_ALLOWED_USERS=YOUR_USER_ID
 3. **Get tokens:**
   - Bot Token (`xoxb-...`): OAuth & Permissions → Install to Workspace
   - App Token (`xapp-...`): Basic Information → App-Level Tokens → Generate
-4. **Configure:**
+4. **Configure:** Run `hermes gateway setup` and select Slack, or add to `~/.hermes/.env` manually:

 ```bash
-# Add to ~/.hermes/.env:
 SLACK_BOT_TOKEN=xoxb-...
 SLACK_APP_TOKEN=xapp-...
 SLACK_ALLOWED_USERS=U01234ABCDE    # Comma-separated Slack user IDs
@@ -423,6 +431,7 @@ hermes uninstall          # Uninstall (can keep configs for later reinstall)

 # Gateway (messaging + cron scheduler)
 hermes gateway            # Run gateway in foreground
+hermes gateway setup      # Configure messaging platforms interactively
 hermes gateway install    # Install as system service (messaging + cron)
 hermes gateway status     # Check service status
 hermes whatsapp           # Pair WhatsApp via QR code
--- a/docs/messaging.md
+++ b/docs/messaging.md
@@ -4,27 +4,33 @@ Hermes Agent can connect to messaging platforms like Telegram, Discord, and What

 ## Quick Start

+The easiest way to configure messaging is the interactive wizard:
+
 ```bash
-# 1. Set your bot token(s) in ~/.hermes/.env
-echo 'TELEGRAM_BOT_TOKEN="your_telegram_bot_token"' >> ~/.hermes/.env
-echo 'DISCORD_BOT_TOKEN="your_discord_bot_token"' >> ~/.hermes/.env
-
-# 2. Test the gateway (foreground)
-./scripts/hermes-gateway run
-
-# 3. Install as a system service (runs in background)
-./scripts/hermes-gateway install
-
-# 4. Manage the service
-./scripts/hermes-gateway start
-./scripts/hermes-gateway stop
-./scripts/hermes-gateway restart
-./scripts/hermes-gateway status
+hermes gateway setup        # Configure Telegram, Discord, Slack, WhatsApp
 ```

-**Quick test (without service install):**
+This walks you through each platform with arrow-key selection, handles tokens, allowlists, and home channels, and offers to start/restart the gateway when done.
+
+**Or configure manually** by editing `~/.hermes/.env`:
+
 ```bash
-python cli.py --gateway  # Runs in foreground, useful for debugging
+# Set your bot token(s)
+echo 'TELEGRAM_BOT_TOKEN="your_telegram_bot_token"' >> ~/.hermes/.env
+echo 'DISCORD_BOT_TOKEN="your_discord_bot_token"' >> ~/.hermes/.env
+```
+
+**Then start the gateway:**
+
+```bash
+hermes gateway              # Run in foreground (useful for debugging)
+hermes gateway install      # Install as a system service (runs in background)
+
+# Manage the service
+hermes gateway start
+hermes gateway stop
+hermes gateway restart
+hermes gateway status
 ```

 ## Architecture Overview