better-dsh 0.2.5 → 0.3.0

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

@@ -1,264 +0,0 @@
----
-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

@@ -1,473 +0,0 @@
----
-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)