better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/use-soul-with-hermes.md

@@ -0,0 +1,264 @@
+---
+sidebar_position: 7
+title: "Use SOUL.md with Hermes"
+description: "How to use SOUL.md to shape Hermes Agent's default voice, what belongs there, and how it differs from AGENTS.md and /personality"
+---
+
+# Use SOUL.md with Hermes
+
+`SOUL.md` is the **primary identity** for your Hermes instance. It's the first thing in the system prompt — it defines who the agent is, how it speaks, and what it avoids.
+
+If you want Hermes to feel like the same assistant every time you talk to it — or if you want to replace the Hermes persona entirely with your own — this is the file to use.
+
+## What SOUL.md is for
+
+Use `SOUL.md` for:
+- tone
+- personality
+- communication style
+- how direct or warm Hermes should be
+- what Hermes should avoid stylistically
+- how Hermes should relate to uncertainty, disagreement, and ambiguity
+
+In short:
+- `SOUL.md` is about who Hermes is and how Hermes speaks
+
+## What SOUL.md is not for
+
+Do not use it for:
+- repo-specific coding conventions
+- file paths
+- commands
+- service ports
+- architecture notes
+- project workflow instructions
+
+Those belong in `AGENTS.md`.
+
+A good rule:
+- if it should apply everywhere, put it in `SOUL.md`
+- if it only belongs to one project, put it in `AGENTS.md`
+
+## Where it lives
+
+Hermes now uses only the global SOUL file for the current instance:
+
+```text
+~/.hermes/SOUL.md
+```
+
+If you run Hermes with a custom home directory, it becomes:
+
+```text
+$HERMES_HOME/SOUL.md
+```
+
+## First-run behavior
+
+Hermes automatically seeds a starter `SOUL.md` for you if one does not already exist.
+
+That means most users now begin with a real file they can read and edit immediately.
+
+Important:
+- if you already have a `SOUL.md`, Hermes does not overwrite it
+- if the file exists but is empty, Hermes adds nothing from it to the prompt
+
+## How Hermes uses it
+
+When Hermes starts a session, it reads `SOUL.md` from `HERMES_HOME`, scans it for prompt-injection patterns, truncates it if needed, and uses it as the **agent identity** — slot #1 in the system prompt. This means SOUL.md completely replaces the built-in default identity text.
+
+If SOUL.md is missing, empty, or cannot be loaded, Hermes falls back to a built-in default identity.
+
+No wrapper language is added around the file. The content itself matters — write the way you want your agent to think and speak.
+
+## A good first edit
+
+If you do nothing else, open the file and change just a few lines so it feels like you.
+
+For example:
+
+```markdown
+You are direct, calm, and technically precise.
+Prefer substance over politeness theater.
+Push back clearly when an idea is weak.
+Keep answers compact unless deeper detail is useful.
+```
+
+That alone can noticeably change how Hermes feels.
+
+## Example styles
+
+### 1. Pragmatic engineer
+
+```markdown
+You are a pragmatic senior engineer.
+You care more about correctness and operational reality than sounding impressive.
+
+## Style
+- Be direct
+- Be concise unless complexity requires depth
+- Say when something is a bad idea
+- Prefer practical tradeoffs over idealized abstractions
+
+## Avoid
+- Sycophancy
+- Hype language
+- Overexplaining obvious things
+```
+
+### 2. Research partner
+
+```markdown
+You are a thoughtful research collaborator.
+You are curious, honest about uncertainty, and excited by unusual ideas.
+
+## Style
+- Explore possibilities without pretending certainty
+- Distinguish speculation from evidence
+- Ask clarifying questions when the idea space is underspecified
+- Prefer conceptual depth over shallow completeness
+```
+
+### 3. Teacher / explainer
+
+```markdown
+You are a patient technical teacher.
+You care about understanding, not performance.
+
+## Style
+- Explain clearly
+- Use examples when they help
+- Do not assume prior knowledge unless the user signals it
+- Build from intuition to details
+```
+
+### 4. Tough reviewer
+
+```markdown
+You are a rigorous reviewer.
+You are fair, but you do not soften important criticism.
+
+## Style
+- Point out weak assumptions directly
+- Prioritize correctness over harmony
+- Be explicit about risks and tradeoffs
+- Prefer blunt clarity to vague diplomacy
+```
+
+## What makes a strong SOUL.md?
+
+A strong `SOUL.md` is:
+- stable
+- broadly applicable
+- specific in voice
+- not overloaded with temporary instructions
+
+A weak `SOUL.md` is:
+- full of project details
+- contradictory
+- trying to micro-manage every response shape
+- mostly generic filler like "be helpful" and "be clear"
+
+Hermes already tries to be helpful and clear. `SOUL.md` should add real personality and style, not restate obvious defaults.
+
+## Suggested structure
+
+You do not need headings, but they help.
+
+A simple structure that works well:
+
+```markdown
+# Identity
+Who Hermes is.
+
+# Style
+How Hermes should sound.
+
+# Avoid
+What Hermes should not do.
+
+# Defaults
+How Hermes should behave when ambiguity appears.
+```
+
+## SOUL.md vs /personality
+
+These are complementary.
+
+Use `SOUL.md` for your durable baseline.
+Use `/personality` for temporary mode switches.
+
+Examples:
+- your default SOUL is pragmatic and direct
+- then for one session you use `/personality teacher`
+- later you switch back without changing your base voice file
+
+## SOUL.md vs AGENTS.md
+
+This is the most common mistake.
+
+### Put this in SOUL.md
+- “Be direct.”
+- “Avoid hype language.”
+- “Prefer short answers unless depth helps.”
+- “Push back when the user is wrong.”
+
+### Put this in AGENTS.md
+- “Use pytest, not unittest.”
+- “Frontend lives in `frontend/`.”
+- “Never edit migrations directly.”
+- “The API runs on port 8000.”
+
+## How to edit it
+
+```bash
+nano ~/.hermes/SOUL.md
+```
+
+or
+
+```bash
+vim ~/.hermes/SOUL.md
+```
+
+Then restart Hermes or start a new session.
+
+## A practical workflow
+
+1. Start with the seeded default file
+2. Trim anything that does not feel like the voice you want
+3. Add 4–8 lines that clearly define tone and defaults
+4. Talk to Hermes for a while
+5. Adjust based on what still feels off
+
+That iterative approach works better than trying to design the perfect personality in one shot.
+
+## Troubleshooting
+
+### I edited SOUL.md but Hermes still sounds the same
+
+Check:
+- you edited `~/.hermes/SOUL.md` or `$HERMES_HOME/SOUL.md`
+- not some repo-local `SOUL.md`
+- the file is not empty
+- your session was restarted after the edit
+- a `/personality` overlay is not dominating the result
+
+### Hermes is ignoring parts of my SOUL.md
+
+Possible causes:
+- higher-priority instructions are overriding it
+- the file includes conflicting guidance
+- the file is too long and got truncated
+- some of the text resembles prompt-injection content and may be blocked or altered by the scanner
+
+### My SOUL.md became too project-specific
+
+Move project instructions into `AGENTS.md` and keep `SOUL.md` focused on identity and style.
+
+## Related docs
+
+- [Personality & SOUL.md](/user-guide/features/personality)
+- [Context Files](/user-guide/features/context-files)
+- [Configuration](/user-guide/configuration)
+- [Tips & Best Practices](/guides/tips)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/use-voice-mode-with-hermes.md

@@ -0,0 +1,473 @@
+---
+sidebar_position: 8
+title: "Use Voice Mode with Hermes"
+description: "A practical guide to setting up and using Hermes voice mode across CLI, Telegram, Discord, and Discord voice channels"
+---
+
+# Use Voice Mode with Hermes
+
+This guide is the practical companion to the [Voice Mode feature reference](/user-guide/features/voice-mode).
+
+If the feature page explains what voice mode can do, this guide shows how to actually use it well.
+
+:::tip
+[Nous Portal](/integrations/nous-portal) bundles both the LLM and TTS through one OAuth — voice mode works end-to-end with no extra credentials.
+:::
+
+## What voice mode is good for
+
+Voice mode is especially useful when:
+- you want a hands-free CLI workflow
+- you want spoken responses in Telegram or Discord
+- you want Hermes sitting in a Discord voice channel for live conversation
+- you want quick idea capture, debugging, or back-and-forth while walking around instead of typing
+
+## Choose your voice mode setup
+
+There are really three different voice experiences in Hermes.
+
+| Mode | Best for | Platform |
+|---|---|---|
+| Interactive microphone loop | Personal hands-free use while coding or researching | CLI |
+| Voice replies in chat | Spoken responses alongside normal messaging | Telegram, Discord |
+| Live voice channel bot | Group or personal live conversation in a VC | Discord voice channels |
+
+A good path is:
+1. get text working first
+2. enable voice replies second
+3. move to Discord voice channels last if you want the full experience
+
+## Step 1: make sure normal Hermes works first
+
+Before touching voice mode, verify that:
+- Hermes starts
+- your provider is configured
+- the agent can answer text prompts normally
+
+```bash
+hermes
+```
+
+Ask something simple:
+
+```text
+What tools do you have available?
+```
+
+If that is not solid yet, fix text mode first.
+
+## Step 2: install the right extras
+
+### CLI microphone + playback
+
+```bash
+cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"
+```
+
+### Messaging platforms
+
+```bash
+cd ~/.hermes/hermes-agent && uv pip install -e ".[messaging]"
+```
+
+### Premium ElevenLabs TTS
+
+```bash
+cd ~/.hermes/hermes-agent && uv pip install -e ".[tts-premium]"
+```
+
+### Local NeuTTS (optional)
+
+```bash
+python -m pip install -U neutts[all]
+```
+
+### Everything
+
+```bash
+cd ~/.hermes/hermes-agent && uv pip install -e ".[all]"
+```
+
+## Step 3: install system dependencies
+
+### macOS
+
+```bash
+brew install portaudio ffmpeg opus
+brew install espeak-ng
+```
+
+### Ubuntu / Debian
+
+```bash
+sudo apt install portaudio19-dev ffmpeg libopus0
+sudo apt install espeak-ng
+```
+
+Why these matter:
+- `portaudio` → microphone input / playback for CLI voice mode
+- `ffmpeg` → audio conversion for TTS and messaging delivery
+- `opus` → Discord voice codec support
+- `espeak-ng` → phonemizer backend for NeuTTS
+
+## Step 4: choose STT and TTS providers
+
+Hermes supports both local and cloud speech stacks.
+
+### Easiest / cheapest setup
+
+Use local STT and free Edge TTS:
+- STT provider: `local`
+- TTS provider: `edge`
+
+This is usually the best place to start.
+
+### Environment file example
+
+Add to `~/.hermes/.env`:
+
+```bash
+# Cloud STT options (local needs no key)
+GROQ_API_KEY=***
+VOICE_TOOLS_OPENAI_KEY=***
+
+# Premium TTS (optional)
+ELEVENLABS_API_KEY=***
+```
+
+### Provider recommendations
+
+#### Speech-to-text
+
+- `local` → best default for privacy and zero-cost use
+- `groq` → very fast cloud transcription
+- `openai` → good paid fallback
+
+#### Text-to-speech
+
+- `edge` → free and good enough for most users
+- `neutts` → free local/on-device TTS
+- `elevenlabs` → best quality
+- `openai` → good middle ground
+- `mistral` → multilingual, native Opus
+
+### If you use `hermes setup`
+
+If you choose NeuTTS in the setup wizard, Hermes checks whether `neutts` is already installed. If it is missing, the wizard tells you NeuTTS needs the Python package `neutts` and the system package `espeak-ng`, offers to install them for you, installs `espeak-ng` with your platform package manager, and then runs:
+
+```bash
+python -m pip install -U neutts[all]
+```
+
+If you skip that install or it fails, the wizard falls back to Edge TTS.
+
+## Step 5: recommended config
+
+```yaml
+voice:
+  record_key: "ctrl+b"
+  submit_mode: "direct"  # TUI: direct | draft
+  max_recording_seconds: 120
+  auto_tts: false
+  beep_enabled: true
+  silence_threshold: 200
+  silence_duration: 3.0
+
+stt:
+  provider: "local"
+  local:
+    model: "base"
+
+tts:
+  provider: "edge"
+  edge:
+    voice: "en-US-AriaNeural"
+```
+
+This is a good conservative default for most people.
+
+In the TUI, `voice.submit_mode` controls what happens after transcription:
+
+- `direct` (default) submits the transcript immediately.
+- `draft` puts the transcript in the composer so you can edit or cancel it before pressing Enter.
+
+For editable voice drafts, set:
+
+```yaml
+voice:
+  submit_mode: "draft"
+```
+
+If you want local TTS instead, switch the `tts` block to:
+
+```yaml
+tts:
+  provider: "neutts"
+  neutts:
+    ref_audio: ''
+    ref_text: ''
+    model: neuphonic/neutts-air-q4-gguf
+    device: cpu
+```
+
+## Use case 1: CLI voice mode
+
+## Turn it on
+
+Start Hermes:
+
+```bash
+hermes
+```
+
+Inside the CLI:
+
+```text
+/voice on
+```
+
+### Recording flow
+
+Default key:
+- `Ctrl+B`
+
+Workflow:
+1. press `Ctrl+B`
+2. speak
+3. wait for silence detection to stop recording automatically
+4. Hermes transcribes and responds
+5. if TTS is on, it speaks the answer
+6. the loop can automatically restart for continuous use
+
+### Useful commands
+
+```text
+/voice
+/voice on
+/voice off
+/voice tts
+/voice status
+```
+
+### Good CLI workflows
+
+#### Walk-up debugging
+
+Say:
+
+```text
+I keep getting a docker permission error. Help me debug it.
+```
+
+Then continue hands-free:
+- "Read the last error again"
+- "Explain the root cause in simpler terms"
+- "Now give me the exact fix"
+
+#### Research / brainstorming
+
+Great for:
+- walking around while thinking
+- dictating half-formed ideas
+- asking Hermes to structure your thoughts in real time
+
+#### Accessibility / low-typing sessions
+
+If typing is inconvenient, voice mode is one of the fastest ways to stay in the full Hermes loop.
+
+## Tuning CLI behavior
+
+### Silence threshold
+
+If Hermes starts/stops too aggressively, tune:
+
+```yaml
+voice:
+  silence_threshold: 250
+```
+
+Higher threshold = less sensitive.
+
+### Silence duration
+
+If you pause a lot between sentences, increase:
+
+```yaml
+voice:
+  silence_duration: 4.0
+```
+
+### Record key
+
+If `Ctrl+B` conflicts with your terminal or tmux habits:
+
+```yaml
+voice:
+  record_key: "ctrl+space"
+```
+
+## Use case 2: voice replies in Telegram or Discord
+
+This mode is simpler than full voice channels.
+
+Hermes stays a normal chat bot, but can speak replies.
+
+### Start the gateway
+
+```bash
+hermes gateway
+```
+
+### Turn on voice replies
+
+Inside Telegram or Discord:
+
+```text
+/voice on
+```
+
+or
+
+```text
+/voice tts
+```
+
+### Modes
+
+| Mode | Meaning |
+|---|---|
+| `off` | text only |
+| `voice_only` | speak only when the user sent voice |
+| `all` | speak every reply |
+
+### When to use which mode
+
+- `/voice on` if you want spoken replies only for voice-originating messages
+- `/voice tts` if you want a full spoken assistant all the time
+
+### Good messaging workflows
+
+#### Telegram assistant on your phone
+
+Use when:
+- you are away from your machine
+- you want to send voice notes and get quick spoken replies
+- you want Hermes to function like a portable research or ops assistant
+
+#### Discord DMs with spoken output
+
+Useful when you want private interaction without server-channel mention behavior.
+
+## Use case 3: Discord voice channels
+
+This is the most advanced mode.
+
+Hermes joins a Discord VC, listens to user speech, transcribes it, runs the normal agent pipeline, and speaks replies back into the channel.
+
+## Required Discord permissions
+
+In addition to the normal text-bot setup, make sure the bot has:
+- Connect
+- Speak
+- preferably Use Voice Activity
+
+Also enable privileged intents in the Developer Portal:
+- Presence Intent
+- Server Members Intent
+- Message Content Intent
+
+## Join and leave
+
+In a Discord text channel where the bot is present:
+
+```text
+/voice join
+/voice leave
+/voice status
+```
+
+### What happens when joined
+
+- users speak in the VC
+- Hermes detects speech boundaries
+- transcripts are posted in the associated text channel
+- Hermes responds in text and audio
+- the text channel is the one where `/voice join` was issued
+
+### Best practices for Discord VC use
+
+- keep `DISCORD_ALLOWED_USERS` tight
+- use a dedicated bot/testing channel at first
+- verify STT and TTS work in ordinary text-chat voice mode before trying VC mode
+
+## Voice quality recommendations
+
+### Best quality setup
+
+- STT: local `large-v3` or Groq `whisper-large-v3`
+- TTS: ElevenLabs
+
+### Best speed / convenience setup
+
+- STT: local `base` or Groq
+- TTS: Edge
+
+### Best zero-cost setup
+
+- STT: local
+- TTS: Edge
+
+## Common failure modes
+
+### "No audio device found"
+
+Install `portaudio`.
+
+### "Bot joins but hears nothing"
+
+Check:
+- your Discord user ID is in `DISCORD_ALLOWED_USERS`
+- you are not muted
+- privileged intents are enabled
+- the bot has Connect/Speak permissions
+
+### "It transcribes but does not speak"
+
+Check:
+- TTS provider config
+- API key / quota for ElevenLabs or OpenAI
+- `ffmpeg` install for Edge conversion paths
+
+### "Whisper outputs garbage"
+
+Try:
+- quieter environment
+- higher `silence_threshold`
+- different STT provider/model
+- shorter, clearer utterances
+
+### "It works in DMs but not in server channels"
+
+That is often mention policy.
+
+By default, the bot needs an `@mention` in Discord server text channels unless configured otherwise.
+
+## Suggested first-week setup
+
+If you want the shortest path to success:
+
+1. get text Hermes working
+2. run `hermes setup tts` to enable voice support
+3. use CLI voice mode with local STT + Edge TTS
+4. then enable `/voice on` in Telegram or Discord
+5. only after that, try Discord VC mode
+
+That progression keeps the debugging surface small.
+
+## Where to read next
+
+- [Voice Mode feature reference](/user-guide/features/voice-mode)
+- [Messaging Gateway](/user-guide/messaging)
+- [Discord setup](/user-guide/messaging/discord)
+- [Telegram setup](/user-guide/messaging/telegram)
+- [Configuration](/user-guide/configuration)