better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/team-telegram-assistant.md

@@ -0,0 +1,441 @@
+---
+sidebar_position: 4
+title: "Tutorial: Team Telegram Assistant"
+description: "Step-by-step guide to setting up a Telegram bot that your whole team can use for code help, research, system admin, and more"
+---
+
+# Set Up a Team Telegram Assistant
+
+This tutorial walks you through setting up a Telegram bot powered by Hermes Agent that multiple team members can use. By the end, your team will have a shared AI assistant they can message for help with code, research, system administration, and anything else — secured with per-user authorization.
+
+## What We're Building
+
+A Telegram bot that:
+
+- **Any authorized team member** can DM for help — code reviews, research, shell commands, debugging
+- **Runs on your server** with full tool access — terminal, file editing, web search, code execution
+- **Per-user sessions** — each person gets their own conversation context
+- **Secure by default** — only approved users can interact, with two authorization methods
+- **Scheduled tasks** — daily standups, health checks, and reminders delivered to a team channel
+
+---
+
+## Prerequisites
+
+Before starting, make sure you have:
+
+- **Hermes Agent installed** on a server or VPS (not your laptop — the bot needs to stay running). Follow the [installation guide](/getting-started/installation) if you haven't yet.
+- **A Telegram account** for yourself (the bot owner)
+- **An LLM provider configured** — at minimum, an API key for OpenAI, Anthropic, or another supported provider in `~/.hermes/.env`
+
+:::tip
+A $5/month VPS is plenty for running the gateway. Hermes itself is lightweight — the LLM API calls are what cost money, and those happen remotely.
+:::
+
+---
+
+## Step 1: Create a Telegram Bot
+
+Every Telegram bot starts with **@BotFather** — Telegram's official bot for creating bots.
+
+1. **Open Telegram** and search for `@BotFather`, or go to [t.me/BotFather](https://t.me/BotFather)
+
+2. **Send `/newbot`** — BotFather will ask you two things:
+   - **Display name** — what users see (e.g., `Team Hermes Assistant`)
+   - **Username** — must end in `bot` (e.g., `myteam_hermes_bot`)
+
+3. **Copy the bot token** — BotFather replies with something like:
+   ```
+   Use this token to access the HTTP API:
+   7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
+   ```
+   Save this token — you'll need it in the next step.
+
+4. **Set a description** (optional but recommended):
+   ```
+   /setdescription
+   ```
+   Choose your bot, then enter something like:
+   ```
+   Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more.
+   ```
+
+5. **Set bot commands** (optional — gives users a command menu):
+   ```
+   /setcommands
+   ```
+   Choose your bot, then paste:
+   ```
+   new - Start a fresh conversation
+   model - Show or change the AI model
+   status - Show session info
+   help - Show available commands
+   stop - Stop the current task
+   ```
+
+:::warning
+Keep your bot token secret. Anyone with the token can control the bot. If it leaks, use `/revoke` in BotFather to generate a new one.
+:::
+
+---
+
+## Step 2: Configure the Gateway
+
+You have two options: the interactive setup wizard (recommended) or manual configuration.
+
+### Option A: Interactive Setup (Recommended)
+
+```bash
+hermes gateway setup
+```
+
+This walks you through everything with arrow-key selection. Pick **Telegram**, paste your bot token, and enter your user ID when prompted.
+
+### Option B: Manual Configuration
+
+Add these lines to `~/.hermes/.env`:
+
+```bash
+# Telegram bot token from BotFather
+TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...
+
+# Your Telegram user ID (numeric)
+TELEGRAM_ALLOWED_USERS=123456789
+```
+
+### Finding Your User ID
+
+Your Telegram user ID is a numeric value (not your username). To find it:
+
+1. Message [@userinfobot](https://t.me/userinfobot) on Telegram
+2. It instantly replies with your numeric user ID
+3. Copy that number into `TELEGRAM_ALLOWED_USERS`
+
+:::info
+Telegram user IDs are permanent numbers like `123456789`. They're different from your `@username`, which can change. Always use the numeric ID for allowlists.
+:::
+
+---
+
+## Step 3: Start the Gateway
+
+### Quick Test
+
+Run the gateway in the foreground first to make sure everything works:
+
+```bash
+hermes gateway
+```
+
+You should see output like:
+
+```
+[Gateway] Starting Hermes Gateway...
+[Gateway] Telegram adapter connected
+[Gateway] Cron scheduler started (tick every 60s)
+```
+
+Open Telegram, find your bot, and send it a message. If it replies, you're in business. Press `Ctrl+C` to stop.
+
+### Production: Install as a Service
+
+For a persistent deployment that survives reboots:
+
+```bash
+hermes gateway install
+sudo hermes gateway install --system   # Linux only: boot-time system service
+```
+
+This creates a background service: a user-level **systemd** service on Linux by default, a **launchd** service on macOS, or a boot-time Linux system service if you pass `--system`.
+
+```bash
+# Linux — manage the default user service
+hermes gateway start
+hermes gateway stop
+hermes gateway status
+
+# View live logs
+journalctl --user -u hermes-gateway -f
+
+# Keep running after SSH logout
+sudo loginctl enable-linger $USER
+
+# Linux servers — explicit system-service commands
+sudo hermes gateway start --system
+sudo hermes gateway status --system
+journalctl -u hermes-gateway -f
+```
+
+```bash
+# macOS — manage the service
+hermes gateway start
+hermes gateway stop
+tail -f ~/.hermes/logs/gateway.log
+```
+
+:::tip macOS PATH
+The launchd plist captures your shell PATH at install time so gateway subprocesses can find tools like Node.js and ffmpeg. If you install new tools later, re-run `hermes gateway install` to update the plist.
+:::
+
+### Verify It's Running
+
+```bash
+hermes gateway status
+```
+
+Then send a test message to your bot on Telegram. You should get a response within a few seconds.
+
+---
+
+## Step 4: Set Up Team Access
+
+Now let's give your teammates access. There are two approaches.
+
+### Approach A: Static Allowlist
+
+Collect each team member's Telegram user ID (have them message [@userinfobot](https://t.me/userinfobot)) and add them as a comma-separated list:
+
+```bash
+# In ~/.hermes/.env
+TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555
+```
+
+Restart the gateway after changes:
+
+```bash
+hermes gateway stop && hermes gateway start
+```
+
+### Approach B: DM Pairing (Recommended for Teams)
+
+DM pairing is more flexible — you don't need to collect user IDs upfront. Here's how it works:
+
+1. **Teammate DMs the bot** — since they're not on the allowlist, the bot replies with a one-time pairing code:
+   ```
+   🔐 Pairing code: XKGH5N7P
+   Send this code to the bot owner for approval.
+   ```
+
+2. **Teammate sends you the code** (via any channel — Slack, email, in person)
+
+3. **You approve it** on the server:
+   ```bash
+   hermes pairing approve telegram XKGH5N7P
+   ```
+
+4. **They're in** — the bot immediately starts responding to their messages
+
+**Managing paired users:**
+
+```bash
+# See all pending and approved users
+hermes pairing list
+
+# Revoke someone's access
+hermes pairing revoke telegram 987654321
+
+# Clear expired pending codes
+hermes pairing clear-pending
+```
+
+:::tip
+DM pairing is ideal for teams because you don't need to restart the gateway when adding new users. Approvals take effect immediately.
+:::
+
+### Security Considerations
+
+- **Never set `GATEWAY_ALLOW_ALL_USERS=true`** on a bot with terminal access — anyone who finds your bot could run commands on your server
+- Pairing codes expire after **1 hour** and use cryptographic randomness
+- Rate limiting prevents brute-force attacks: 1 request per user per 10 minutes, max 3 pending codes per platform
+- After 5 failed approval attempts, the platform enters a 1-hour lockout
+- All pairing data is stored with `chmod 0600` permissions
+
+---
+
+## Step 5: Configure the Bot
+
+### Set a Home Channel
+
+A **home channel** is where the bot delivers cron job results and proactive messages. Without one, scheduled tasks have nowhere to send output.
+
+**Option 1:** Use the `/sethome` command in any Telegram group or chat where the bot is a member.
+
+**Option 2:** Set it manually in `~/.hermes/.env`:
+
+```bash
+TELEGRAM_HOME_CHANNEL=-1001234567890
+TELEGRAM_HOME_CHANNEL_NAME="Team Updates"
+```
+
+To find a channel ID, add [@userinfobot](https://t.me/userinfobot) to the group — it will report the group's chat ID.
+
+### Configure Tool Progress Display
+
+Control how much detail the bot shows when using tools. In `~/.hermes/config.yaml`:
+
+```yaml
+display:
+  tool_progress: new    # off | new | all | verbose
+```
+
+| Mode | What You See |
+|------|-------------|
+| `off` | Clean responses only — no tool activity |
+| `new` | Brief status for each new tool call (recommended for messaging) |
+| `all` | Every tool call with details |
+| `verbose` | Full tool output including command results |
+
+Users can also change this per-session with the `/verbose` command in chat.
+
+### Set Up a Personality with SOUL.md
+
+Customize how the bot communicates by editing `~/.hermes/SOUL.md`:
+
+For a full guide, see [Use SOUL.md with Hermes](/guides/use-soul-with-hermes).
+
+```markdown
+# Soul
+You are a helpful team assistant. Be concise and technical.
+Use code blocks for any code. Skip pleasantries — the team
+values directness. When debugging, always ask for error logs
+before guessing at solutions.
+```
+
+### Add Project Context
+
+If your team works on specific projects, create context files so the bot knows your stack:
+
+```markdown
+<!-- ~/.hermes/AGENTS.md -->
+# Team Context
+- We use Python 3.12 with FastAPI and SQLAlchemy
+- Frontend is React with TypeScript
+- CI/CD runs on GitHub Actions
+- Production deploys to AWS ECS
+- Always suggest writing tests for new code
+```
+
+:::info
+Context files are injected into every session's system prompt. Keep them concise — every character counts against your token budget.
+:::
+
+---
+
+## Step 6: Set Up Scheduled Tasks
+
+With the gateway running, you can schedule recurring tasks that deliver results to your team channel.
+
+### Daily Standup Summary
+
+Message the bot on Telegram:
+
+```
+Every weekday at 9am, check the GitHub repository at
+github.com/myorg/myproject for:
+1. Pull requests opened/merged in the last 24 hours
+2. Issues created or closed
+3. Any CI/CD failures on the main branch
+Format as a brief standup-style summary.
+```
+
+The agent creates a cron job automatically and delivers results to the chat where you asked (or the home channel).
+
+### Server Health Check
+
+```
+Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
+and Docker container status with 'docker ps'. Report anything unusual —
+partitions above 80%, containers that have restarted, or high memory usage.
+```
+
+### Managing Scheduled Tasks
+
+```bash
+# From the CLI
+hermes cron list          # View all scheduled jobs
+hermes cron status        # Check if scheduler is running
+
+# From Telegram chat
+/cron list                # View jobs
+/cron remove <job_id>     # Remove a job
+```
+
+:::warning
+Cron job prompts run in completely fresh sessions with no memory of prior conversations. Make sure each prompt contains **all** the context the agent needs — file paths, URLs, server addresses, and clear instructions.
+:::
+
+---
+
+## Production Tips
+
+### Use Docker for Safety
+
+On a shared team bot, use Docker as the terminal backend so agent commands run in a container instead of on your host:
+
+```bash
+# In ~/.hermes/.env
+TERMINAL_ENV=docker
+TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
+```
+
+Or in `~/.hermes/config.yaml`:
+
+```yaml
+terminal:
+  backend: docker
+  container_cpu: 1
+  container_memory: 5120
+  container_persistent: true
+```
+
+This way, even if someone asks the bot to run something destructive, your host system is protected.
+
+### Monitor the Gateway
+
+```bash
+# Check if the gateway is running
+hermes gateway status
+
+# Watch live logs (Linux)
+journalctl --user -u hermes-gateway -f
+
+# Watch live logs (macOS)
+tail -f ~/.hermes/logs/gateway.log
+```
+
+### Keep Hermes Updated
+
+From Telegram, send `/update` to the bot — it will pull the latest version and restart. Or from the server:
+
+```bash
+hermes update
+hermes gateway stop && hermes gateway start
+```
+
+### Log Locations
+
+| What | Location |
+|------|----------|
+| Gateway logs | `journalctl --user -u hermes-gateway` (Linux) or `~/.hermes/logs/gateway.log` (macOS) |
+| Cron job output | `~/.hermes/cron/output/{job_id}/{timestamp}.md` |
+| Cron job definitions | `~/.hermes/cron/jobs.json` |
+| Pairing data | `~/.hermes/pairing/` |
+| Session history | `~/.hermes/sessions/` |
+
+---
+
+## Going Further
+
+You've got a working team Telegram assistant. Here are some next steps:
+
+- **[Security Guide](/user-guide/security)** — deep dive into authorization, container isolation, and command approval
+- **[Messaging Gateway](/user-guide/messaging)** — full reference for gateway architecture, session management, and chat commands
+- **[Telegram Setup](/user-guide/messaging/telegram)** — platform-specific details including voice messages and TTS
+- **[Scheduled Tasks](/user-guide/features/cron)** — advanced cron scheduling with delivery options and cron expressions
+- **[Context Files](/user-guide/features/context-files)** — AGENTS.md, SOUL.md, and .cursorrules for project knowledge
+- **[Personality](/user-guide/features/personality)** — built-in personality presets and custom persona definitions
+- **Add more platforms** — the same gateway can simultaneously run [Discord](/user-guide/messaging/discord), [Slack](/user-guide/messaging/slack), and [WhatsApp](/user-guide/messaging/whatsapp)
+
+---
+
+*Questions or issues? Open an issue on GitHub — contributions are welcome.*

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/tips.md

@@ -0,0 +1,238 @@
+---
+sidebar_position: 1
+title: "Tips & Best Practices"
+description: "Practical advice to get the most out of Hermes Agent — prompt tips, CLI shortcuts, context files, memory, cost optimization, and security"
+---
+
+# Tips & Best Practices
+
+A quick-wins collection of practical tips that make you immediately more effective with Hermes Agent. Each section targets a different aspect — scan the headers and jump to what's relevant.
+
+:::tip Confused which model to pick?
+Run `hermes setup --portal` — you get 300+ models including Claude, GPT-5, and Gemini under one subscription. See [Nous Portal](/integrations/nous-portal).
+:::
+
+---
+
+## Getting the Best Results
+
+### Be Specific About What You Want
+
+Vague prompts produce vague results. Instead of "fix the code," say "fix the TypeError in `api/handlers.py` on line 47 — the `process_request()` function receives `None` from `parse_body()`." The more context you give, the fewer iterations you need.
+
+### Provide Context Up Front
+
+Front-load your request with the relevant details: file paths, error messages, expected behavior. One well-crafted message beats three rounds of clarification. Paste error tracebacks directly — the agent can parse them.
+
+### Use Context Files for Recurring Instructions
+
+If you find yourself repeating the same instructions ("use tabs not spaces," "we use pytest," "the API is at `/api/v2`"), put them in an `AGENTS.md` file. The agent reads it automatically every session — zero effort after setup.
+
+### Let the Agent Use Its Tools
+
+Don't try to hand-hold every step. Say "find and fix the failing test" rather than "open `tests/test_foo.py`, look at line 42, then..." The agent has file search, terminal access, and code execution — let it explore and iterate.
+
+### Use Skills for Complex Workflows
+
+Before writing a long prompt explaining how to do something, check if there's already a skill for it. Type `/skills` to browse available skills, or just invoke one directly like `/axolotl` or `/github-pr-workflow`.
+
+## CLI Power User Tips
+
+### Multi-Line Input
+
+Press **Alt+Enter**, **Ctrl+J**, or **Shift+Enter** to insert a newline without sending. `Shift+Enter` only works when the terminal sends it as a distinct keystroke (Kitty / foot / WezTerm / Ghostty by default; iTerm2 / Alacritty / VS Code terminal once the Kitty keyboard protocol is enabled). The other two work in every terminal.
+
+### Paste Detection
+
+The CLI auto-detects multi-line pastes. Just paste a code block or error traceback directly — it won't send each line as a separate message. The paste is buffered and sent as one message.
+
+### Interrupt and Redirect
+
+Press **Ctrl+C** once to interrupt the agent mid-response. You can then type a new message to redirect it. Double-press Ctrl+C within 2 seconds to force exit. This is invaluable when the agent starts going down the wrong path.
+
+### Resume Sessions with `-c`
+
+Forgot something from your last session? Run `hermes -c` to resume exactly where you left off, with full conversation history restored. You can also resume by title: `hermes -r "my research project"`.
+
+### Clipboard Image Paste
+
+Press **Ctrl+V** to paste an image from your clipboard directly into the chat. The agent uses vision to analyze screenshots, diagrams, error popups, or UI mockups — no need to save to a file first.
+
+### Slash Command Autocomplete
+
+Type `/` and press **Tab** to see all available commands. This includes built-in commands (`/compress`, `/model`, `/title`) and every installed skill. You don't need to memorize anything — Tab completion has you covered.
+
+:::tip
+Use `/verbose` to cycle through tool output display modes: **off → new → all → verbose**. The "all" mode is great for watching what the agent does; "off" is cleanest for simple Q&A.
+:::
+
+## Context Files
+
+### AGENTS.md: Your Project's Brain
+
+Create an `AGENTS.md` in your project root with architecture decisions, coding conventions, and project-specific instructions. This is automatically injected into every session, so the agent always knows your project's rules.
+
+```markdown
+# Project Context
+- This is a FastAPI backend with SQLAlchemy ORM
+- Always use async/await for database operations
+- Tests go in tests/ and use pytest-asyncio
+- Never commit .env files
+```
+
+### SOUL.md: Customize Personality
+
+Want Hermes to have a stable default voice? Edit `~/.hermes/SOUL.md` (or `$HERMES_HOME/SOUL.md` if you use a custom Hermes home). Hermes now seeds a starter SOUL automatically and uses that global file as the instance-wide personality source.
+
+For a full walkthrough, see [Use SOUL.md with Hermes](/guides/use-soul-with-hermes).
+
+```markdown
+# Soul
+You are a senior backend engineer. Be terse and direct.
+Skip explanations unless asked. Prefer one-liners over verbose solutions.
+Always consider error handling and edge cases.
+```
+
+Use `SOUL.md` for durable personality. Use `AGENTS.md` for project-specific instructions.
+
+### .cursorrules Compatibility
+
+Already have a `.cursorrules` or `.cursor/rules/*.mdc` file? Hermes reads those too. No need to duplicate your coding conventions — they're loaded automatically from the working directory.
+
+### Discovery
+
+Hermes loads the top-level `AGENTS.md` from the current working directory at session start. Subdirectory `AGENTS.md` files are discovered lazily during tool calls (via `subdirectory_hints.py`) and injected into tool results — they are not loaded upfront into the system prompt.
+
+:::tip
+Keep context files focused and concise. Every character counts against your token budget since they're injected into every single message.
+:::
+
+## Memory & Skills
+
+### Memory vs. Skills: What Goes Where
+
+**Memory** is for facts: your environment, preferences, project locations, and things the agent has learned about you. **Skills** are for procedures: multi-step workflows, tool-specific instructions, and reusable recipes. Use memory for "what," skills for "how."
+
+### When to Create Skills
+
+If you find a task that takes 5+ steps and you'll do it again, ask the agent to create a skill for it. Say "save what you just did as a skill called `deploy-staging`." Next time, just type `/deploy-staging` and the agent loads the full procedure.
+
+### Managing Memory Capacity
+
+Memory is intentionally bounded (~2,200 chars for MEMORY.md, ~1,375 chars for USER.md). When it fills up, the agent consolidates entries. You can help by saying "clean up your memory" or "replace the old Python 3.9 note — we're on 3.12 now."
+
+### Let the Agent Remember
+
+After a productive session, say "remember this for next time" and the agent will save the key takeaways. You can also be specific: "save to memory that our CI uses GitHub Actions with the `deploy.yml` workflow."
+
+:::warning
+Memory is a frozen snapshot — changes made during a session don't appear in the system prompt until the next session starts. The agent writes to disk immediately, but the prompt cache isn't invalidated mid-session.
+:::
+
+## Performance & Cost
+
+### Don't Break the Prompt Cache
+
+Most LLM providers cache the conversation prefix (system prompt + history). If you keep your system prompt stable (same context files, same memory), subsequent messages in a session get **cache hits** that are significantly cheaper. The cache is keyed to the model and account — so an explicit `/model` switch, an [automatic provider fallback](../user-guide/features/fallback-providers.md), or a [credential-pool rotation](../user-guide/features/credential-pools.md) all force the next turn to re-read the entire conversation at full input price. Occasional switches are fine; frequent switching in a long session multiplies your cost.
+
+### Use /compress Before Hitting Limits
+
+Long sessions accumulate tokens. When you notice responses slowing down or getting truncated, run `/compress`. This summarizes the conversation history, preserving key context while dramatically reducing token count. Use `/usage` to check where you stand.
+
+### Delegate for Parallel Work
+
+Need to research three topics at once? Ask the agent to use `delegate_task` with parallel subtasks. Each subagent runs independently with its own context, and only the final summaries come back — massively reducing your main conversation's token usage.
+
+### Use execute_code for Batch Operations
+
+Instead of running terminal commands one at a time, ask the agent to write a script that does everything at once. "Write a Python script to rename all `.jpeg` files to `.jpg` and run it" is cheaper and faster than renaming files individually.
+
+### Choose the Right Model
+
+Use `/model` to switch models mid-session. Use a frontier model (Claude Sonnet/Opus, GPT-4o) for complex reasoning and architecture decisions. Switch to a faster model for simple tasks like formatting, renaming, or boilerplate generation. Keep in mind each switch resets the prompt cache (see above), so on long sessions it's often cheaper to start a fresh session on the other model than to bounce back and forth.
+
+:::tip
+Run `/usage` periodically to see your token consumption. Run `/insights` for a broader view of usage patterns over the last 30 days. To see what your *fixed* per-message cost is before any conversation — system prompt, skills index, memory, tool schemas — run [`hermes prompt-size`](/reference/cli-commands#hermes-prompt-size) (works offline).
+:::
+
+## Messaging Tips
+
+### Set a Home Channel
+
+Use `/sethome` in your preferred Telegram or Discord chat to designate it as the home channel. Cron job results and scheduled task outputs are delivered here. Without it, the agent has nowhere to send proactive messages.
+
+### Use /title to Organize Sessions
+
+Name your sessions with `/title auth-refactor` or `/title research-llm-quantization`. Named sessions are easy to find with `hermes sessions list` and resume with `hermes -r "auth-refactor"`. Unnamed sessions pile up and become impossible to distinguish.
+
+### DM Pairing for Team Access
+
+Instead of manually collecting user IDs for allowlists, enable DM pairing. When a teammate DMs the bot, they get a one-time pairing code. You approve it with `hermes pairing approve telegram XKGH5N7P` — simple and secure.
+
+### Tool Progress Display Modes
+
+Use `/verbose` to control how much tool activity you see. In messaging platforms, less is usually more — keep it on "new" to see just new tool calls. In the CLI, "all" gives you a satisfying live view of everything the agent does.
+
+:::tip
+Messaging sessions persist until an explicit `/new` or `/reset`. Context compression manages long conversations without an idle or daily reset.
+:::
+
+## Security
+
+### Use Docker for Untrusted Code
+
+When working with untrusted repositories or running unfamiliar code, use Docker or Daytona as your terminal backend. Set `TERMINAL_ENV=docker` in your `.env`. Destructive commands inside a container can't harm your host system.
+
+```bash
+# In your .env:
+TERMINAL_ENV=docker
+TERMINAL_DOCKER_IMAGE=hermes-sandbox:latest
+```
+
+### Avoid Windows Encoding Pitfalls
+
+On Windows, some default encodings (such as `cp125x`) cannot represent all Unicode characters, which can cause `UnicodeEncodeError` when writing files in tests or scripts.
+
+- Prefer opening files with an explicit UTF-8 encoding:
+
+```python
+with open("results.txt", "w", encoding="utf-8") as f:
+    f.write("✓ All good\n")
+```
+
+- In PowerShell, you can also switch the current session to UTF-8 for console and native command output:
+
+```powershell
+$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+```
+
+This keeps PowerShell and child processes on UTF-8 and helps avoid Windows-only failures.
+
+### Review Before Choosing "Always"
+
+When the agent triggers a dangerous command approval (`rm -rf`, `DROP TABLE`, etc.), you get four options: **once**, **session**, **always**, **deny**. Think carefully before choosing "always" — it permanently allowlists that pattern. Start with "session" until you're comfortable.
+
+### Command Approval Is Your Safety Net
+
+Hermes checks every command against a curated list of dangerous patterns before execution. This includes recursive deletes, SQL drops, piping curl to shell, and more. Don't disable this in production — it exists for good reasons.
+
+:::warning
+When running in a container backend (Docker, Singularity, Modal, Daytona), dangerous command checks are **skipped** because the container is the security boundary. Make sure your container images are properly locked down.
+:::
+
+### Use Allowlists for Messaging Bots
+
+Never set `GATEWAY_ALLOW_ALL_USERS=true` on a bot with terminal access. Always use platform-specific allowlists (`TELEGRAM_ALLOWED_USERS`, `DISCORD_ALLOWED_USERS`) or DM pairing to control who can interact with your agent.
+
+```bash
+# Recommended: explicit allowlists per platform
+TELEGRAM_ALLOWED_USERS=123456789,987654321
+DISCORD_ALLOWED_USERS=123456789012345678
+
+# Or use cross-platform allowlist
+GATEWAY_ALLOWED_USERS=123456789,987654321
+```
+
+---
+
+*Have a tip that should be on this page? Open an issue or PR — community contributions are welcome.*