Initial release: Hermes client onboarding bootstrap + skill

One-liner install.sh, conversational skill for OpenRouter/DeepSeek
V4 Flash + Telegram gateway, and DomHubs client demo flow.

skill/hermes-client-onboarding/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: hermes-client-onboarding
+description: Use when setting up Hermes for a client, install Hermes + Telegram + OpenRouter, run a demo setup, or launch client onboarding. Conducts guided conversational onboarding on a clean Linux VM (deepseek/deepseek-v4-flash, Telegram gateway, systemd, SOUL.md).
+version: 1.0.0
+author: DomHubs
+license: MIT
+platforms: [linux, macos]
+metadata:
+  hermes:
+    tags: [onboarding, client, telegram, openrouter, deepseek, gateway, demo]
+    related_skills: []
+---
+
+# Hermes Client Onboarding
+
+## Overview
+
+You are conducting a professional, step-by-step onboarding of Hermes Agent on a clean Ubuntu/Debian VM so a client can start using it immediately (primarily via Telegram). The goal is a working agent in minutes, with OpenRouter + DeepSeek V4 Flash as the default model, Telegram as the primary channel, and the gateway running as a persistent service.
+
+This skill is designed for live demos in front of the client and for commercial handoff. Be clear, structured, and efficient. Always confirm critical values before applying them.
+
+## When to Use
+
+- User asks to set up Hermes for a client
+- Demo setup of Hermes + Telegram + OpenRouter
+- Launch of the DomHubs client onboarding flow
+- Fresh VM that needs Hermes ready end-to-end
+
+Don't use for: day-to-day Hermes coding tasks after onboarding is done; multi-tenant fleet orchestration; non-Hermes agent installs.
+
+## Success Criteria
+
+The onboarding is complete only when all of the following are true:
+
+- Hermes is installed and `hermes` command works
+- Model is set to `deepseek/deepseek-v4-flash` via OpenRouter
+- `OPENROUTER_API_KEY` is configured
+- Telegram bot token and at least one allowed user ID are set
+- Gateway is installed as a systemd service and is running
+- A test message sent to the Telegram bot receives a coherent reply
+- `hermes doctor` reports no critical errors
+- SOUL.md has been personalized (or the user explicitly skipped it)
+
+## Pre-flight Checks (do these first)
+
+Run these checks silently or with minimal output before starting the dialogue:
+
+1. Confirm you are on Linux (preferably Ubuntu 22.04/24.04 or Debian). On macOS, warn that gateway persistence differs (launchd) and demos still work.
+2. Check if `hermes` is already in PATH. If yes, note the version with `hermes --version`.
+3. Check available disk space and RAM (`df -h /` and `free -h`). Warn if RAM < 2 GB or free disk < 5 GB.
+4. Verify internet connectivity (can reach `https://hermes-agent.nousresearch.com` and `https://openrouter.ai`).
+
+If Hermes is missing, install it with:
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
+source ~/.bashrc 2>/dev/null || true
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+After install, confirm with `hermes --version` and `hermes doctor`.
+
+**Done when:** OS/resources known, Hermes on PATH, version recorded.
+
+## Conversational Flow
+
+Conduct the onboarding as a structured dialogue. Move phase by phase. Never skip confirmation of secrets or user IDs.
+
+### Phase 1 — Context & Goals
+
+Ask:
+
+- Is this a live demo in front of the client or a setup you will hand over later?
+- What is the client/company name? (used later in SOUL.md)
+- Preferred language for the agent (default: Portuguese Brazilian)
+- Will the client interact mainly via Telegram? (yes/no — we still set Telegram as primary)
+
+**Done when:** demo vs handoff, company name, language, and channel intent confirmed.
+
+### Phase 2 — OpenRouter Credentials
+
+1. Ask for the OpenRouter API key (format usually starts with `sk-or-v1-`).
+2. Confirm the key is present and looks valid (do not echo the full key back).
+3. Apply it (prefer `scripts/apply-core-config.sh` when you already have Telegram values too; otherwise set now):
+
+```bash
+hermes config set OPENROUTER_API_KEY "THE_KEY"
+hermes config set model.provider openrouter
+hermes config set model.default deepseek/deepseek-v4-flash
+```
+
+4. Verify with:
+
+```bash
+hermes config get model.default
+hermes config get model.provider
+```
+
+Optional: Offer to set a fallback model (e.g. another cheap OpenRouter model) if the user wants resilience.
+
+**Done when:** provider=openrouter, model=deepseek/deepseek-v4-flash, key set without printing it.
+
+### Phase 3 — Telegram Bot
+
+1. Guide the user (or do it yourself if they give you the token) to create a bot with @BotFather if they do not have one yet.
+2. Collect:
+   - `TELEGRAM_BOT_TOKEN`
+   - At least one numeric User ID (from @userinfobot or @get_id_bot). Multiple IDs can be comma-separated.
+3. Apply:
+
+```bash
+hermes config set TELEGRAM_BOT_TOKEN "TOKEN"
+hermes config set TELEGRAM_ALLOWED_USERS "ID1,ID2"
+```
+
+4. Optional advanced settings (only if requested):
+   - Home channel for proactive messages
+   - Group chat IDs
+
+**Done when:** token set, at least one allowed user ID set, values repeated back (IDs only, never full token).
+
+### Phase 4 — Agent Personality (SOUL.md)
+
+Ask how the agent should present itself. Offer a default template and let the user customize.
+
+Default template (adapt with company name and language):
+
+```markdown
+Você é o assistente oficial da [Nome da Empresa].
+Responda sempre em português brasileiro de forma clara, profissional, objetiva e prestativa.
+Você tem memória persistente e pode usar ferramentas para ajudar o usuário em tarefas reais.
+```
+
+Write the final content to `~/.hermes/SOUL.md`. Confirm before overwriting if the file already exists.
+
+**Done when:** SOUL.md written or user explicitly skipped personalization.
+
+### Phase 5 — Gateway & Persistence
+
+1. Install the gateway as a system service:
+
+```bash
+hermes gateway install
+```
+
+2. Start / restart it:
+
+```bash
+hermes gateway start
+# or
+hermes gateway restart
+```
+
+3. Check status:
+
+```bash
+hermes gateway status
+```
+
+4. If the service fails, inspect logs (`hermes gateway logs` or `journalctl -u hermes* -n 50` / `launchctl` on macOS) and fix common issues (PATH, missing env, permissions). See `references/troubleshooting.md`.
+
+**Done when:** gateway status shows running and service is installed for reboot persistence.
+
+### Phase 6 — Validation & Handover
+
+Run the full validation sequence:
+
+```bash
+hermes doctor
+hermes gateway status
+```
+
+Then instruct the user to send a test message to the Telegram bot (“oi” ou “teste”). Confirm that a coherent reply arrives.
+
+Final checklist to present to the user:
+
+- [ ] Hermes installed and in PATH
+- [ ] Model = deepseek/deepseek-v4-flash via OpenRouter
+- [ ] Telegram bot responding
+- [ ] Gateway running as service (survives reboot)
+- [ ] SOUL.md personalized
+- [ ] `hermes doctor` clean
+
+Give the user the useful commands for later:
+
+```bash
+hermes gateway status
+hermes gateway logs
+hermes doctor
+hermes config get model.default
+hermes update
+```
+
+**Done when:** checklist walked, test Telegram reply confirmed, useful commands delivered.
+
+## Error Handling Guidelines
+
+- If `hermes config set` fails, check file permissions on `~/.hermes/.env` and `~/.hermes/config.yaml`.
+- If Telegram does not respond: verify token with a direct `getMe` call, confirm Allowed Users, restart gateway, check logs for connection errors.
+- If OpenRouter returns auth errors: re-validate the key and model name (`deepseek/deepseek-v4-flash`).
+- Prefer fixing issues yourself when possible, then explain what was wrong in plain language.
+- Never leave the system in a half-configured state. Either finish a phase or clearly roll back.
+
+## Style & Tone While Onboarding
+
+- Professional and calm (you are in front of a client or preparing a commercial handoff).
+- Short confirmations after each successful step.
+- Always repeat back critical non-secret values (model name, allowed user IDs, company name).
+- Never print full API keys or bot tokens in the conversation.
+- Prefer Portuguese when the user is speaking Portuguese.
+
+## Optional Extensions (only if requested)
+
+- Add Discord or WhatsApp after Telegram is working.
+- Switch to native DeepSeek provider later (`DEEPSEEK_API_KEY` + provider `deepseek`).
+- Enable extra tools or change terminal backend.
+- Create additional allowlisted users.
+- Set up a simple cron job or home channel for proactive messages.
+
+## Supporting Resources
+
+- `references/troubleshooting.md` — detailed fixes for the most common failures (Telegram not replying, auth errors, service problems, PATH issues).
+- `scripts/apply-core-config.sh` — safe helper to apply OpenRouter key + model + Telegram token + allowed users in one go. Prefer using it when you already have all three values confirmed.
+
+## Reference Commands (quick lookup)
+
+```bash
+# Install
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
+
+# Core config (or use the helper script)
+hermes config set OPENROUTER_API_KEY "sk-or-..."
+hermes config set model.provider openrouter
+hermes config set model.default deepseek/deepseek-v4-flash
+hermes config set TELEGRAM_BOT_TOKEN "..."
+hermes config set TELEGRAM_ALLOWED_USERS "123456789"
+
+# Gateway
+hermes gateway install
+hermes gateway start
+hermes gateway status
+hermes gateway logs
+
+# Validation
+hermes doctor
+hermes --version
+```
+
+When the user says the onboarding is finished or the bot is responding correctly, summarize what was configured and congratulate them. Offer to make any final adjustments.

skill/hermes-client-onboarding/references/troubleshooting.md

@@ -0,0 +1,99 @@
+# Troubleshooting — Hermes Client Onboarding
+
+## PATH / `hermes: command not found`
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# persist
+grep -q '.local/bin' ~/.bashrc 2>/dev/null || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+hash -r
+hermes --version
+```
+
+Re-run install if still missing:
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser
+```
+
+## OpenRouter auth errors
+
+1. Confirm key format (`sk-or-v1-...`) without pasting full key into chat.
+2. Re-set:
+
+```bash
+hermes config set OPENROUTER_API_KEY "THE_KEY"
+hermes config set model.provider openrouter
+hermes config set model.default deepseek/deepseek-v4-flash
+```
+
+3. Check:
+
+```bash
+hermes config get model.default
+hermes config get model.provider
+# key lives in ~/.hermes/.env — never cat full file in front of client
+```
+
+4. Test connectivity: `curl -sI https://openrouter.ai | head -1`
+
+## Telegram bot does not reply
+
+1. Token validity:
+
+```bash
+# TOKEN from env; do not log it
+source ~/.hermes/.env 2>/dev/null || true
+curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe" | head -c 200
+```
+
+2. Allowed users: numeric IDs only (from @userinfobot). Restart after change:
+
+```bash
+hermes config set TELEGRAM_ALLOWED_USERS "ID1,ID2"
+hermes gateway restart
+hermes gateway status
+hermes gateway logs
+```
+
+3. Common mistakes:
+   - User ID is username string instead of numeric ID
+   - Gateway not running
+   - Bot blocked by user / wrong bot
+
+## Gateway service won't start
+
+```bash
+hermes gateway status
+hermes gateway logs
+# Linux
+journalctl -u 'hermes*' -n 80 --no-pager
+# macOS
+# check launchd labels from hermes gateway status
+```
+
+Fixes:
+- Ensure `~/.hermes/.env` readable by the service user
+- Ensure `hermes` on PATH for the service unit (re-run `hermes gateway install`)
+- Free port conflicts if any webhook mode is misconfigured
+
+## `hermes config set` fails
+
+```bash
+ls -la ~/.hermes/.env ~/.hermes/config.yaml
+# fix ownership if needed
+chown "$USER" ~/.hermes/.env ~/.hermes/config.yaml
+chmod 600 ~/.hermes/.env
+```
+
+## `hermes doctor` critical errors
+
+Run `hermes doctor` and fix top critical items first (keys, model, gateway). Warnings about optional tools (browser, extra MCP) can wait until after Telegram works.
+
+## Half-configured state recovery
+
+If onboarding aborted mid-way:
+
+1. `hermes config show` — see what's set
+2. Finish remaining phases from the skill (do not reinstall unless broken)
+3. `hermes gateway restart && hermes doctor`

skill/hermes-client-onboarding/scripts/apply-core-config.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Apply OpenRouter + model + Telegram core config for Hermes client onboarding.
+# Does not print secrets. Requires: hermes on PATH.
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  apply-core-config.sh \
+    --openrouter-key KEY \
+    --telegram-token TOKEN \
+    --allowed-users ID1,ID2 \
+    [--model deepseek/deepseek-v4-flash] \
+    [--provider openrouter]
+
+Env fallbacks (if flags omitted):
+  OPENROUTER_API_KEY, TELEGRAM_BOT_TOKEN, TELEGRAM_ALLOWED_USERS
+EOF
+}
+
+MODEL="deepseek/deepseek-v4-flash"
+PROVIDER="openrouter"
+OR_KEY="${OPENROUTER_API_KEY:-}"
+TG_TOKEN="${TELEGRAM_BOT_TOKEN:-}"
+TG_USERS="${TELEGRAM_ALLOWED_USERS:-}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --openrouter-key) OR_KEY="${2:-}"; shift 2 ;;
+    --telegram-token) TG_TOKEN="${2:-}"; shift 2 ;;
+    --allowed-users)  TG_USERS="${2:-}"; shift 2 ;;
+    --model)          MODEL="${2:-}"; shift 2 ;;
+    --provider)       PROVIDER="${2:-}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 2 ;;
+  esac
+done
+
+if ! command -v hermes >/dev/null 2>&1; then
+  echo "error: hermes not found on PATH" >&2
+  exit 1
+fi
+
+missing=0
+[[ -z "$OR_KEY" ]] && { echo "error: missing OpenRouter key" >&2; missing=1; }
+[[ -z "$TG_TOKEN" ]] && { echo "error: missing Telegram bot token" >&2; missing=1; }
+[[ -z "$TG_USERS" ]] && { echo "error: missing TELEGRAM_ALLOWED_USERS" >&2; missing=1; }
+[[ "$missing" -eq 1 ]] && exit 1
+
+# light validation (no secret echo)
+if [[ ! "$OR_KEY" =~ ^sk-or- ]]; then
+  echo "warn: OpenRouter key does not start with sk-or- (continuing)" >&2
+fi
+if [[ ! "$TG_USERS" =~ ^[0-9]+(,[0-9]+)*$ ]]; then
+  echo "error: allowed users must be numeric IDs, comma-separated" >&2
+  exit 1
+fi
+
+hermes config set OPENROUTER_API_KEY "$OR_KEY"
+hermes config set model.provider "$PROVIDER"
+hermes config set model.default "$MODEL"
+hermes config set TELEGRAM_BOT_TOKEN "$TG_TOKEN"
+hermes config set TELEGRAM_ALLOWED_USERS "$TG_USERS"
+
+echo "ok: provider=$(hermes config get model.provider 2>/dev/null || echo "$PROVIDER")"
+echo "ok: model=$(hermes config get model.default 2>/dev/null || echo "$MODEL")"
+echo "ok: allowed_users=$TG_USERS"
+echo "ok: secrets written (not displayed)"