better-dsh 0.2.4 → 0.2.5-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/mixture-of-agents.md

@@ -0,0 +1,246 @@
+---
+sidebar_position: 7
+title: "Mixture of Agents"
+description: "Create named MoA presets that appear as selectable models under the Mixture of Agents provider"
+---
+
+# Mixture of Agents
+
+Mixture of Agents is a virtual model provider. Each named MoA preset appears as a selectable model under the `moa` provider.
+
+When you select a MoA preset, the preset's aggregator is the acting model. It is the model that writes the assistant response and emits tool calls. Reference models run first and provide analysis for the aggregator to use.
+
+Use MoA when a hard task benefits from multiple model perspectives but still needs Hermes' normal agent loop: tool calls, follow-up iterations, interrupts, transcript persistence, and the same session context as any other message.
+
+## Select a MoA preset as your model
+
+You can select a preset through the normal model picker surfaces:
+
+```bash
+/model default --provider moa
+/model review --provider moa
+```
+
+MoA presets are selectable on **every Hermes surface**, because MoA is a normal provider in the model system:
+
+- **CLI / gateway / TUI `/model`** — `/model <preset> --provider moa`, or `/model --provider moa` for the default preset. A bare `/model <preset>` also works when the name exactly matches a configured preset.
+- **`hermes model`** and the **Dashboard model picker** — a `Mixture of Agents` provider row appears with your preset names as its models.
+- **Desktop GUI app** — the model dropdown shows an `MoA presets` section; selecting one (`MoA: <preset>`) switches the active model to that preset. The Desktop settings panel also creates and edits presets.
+
+Configured presets therefore show up wherever you would pick any other model.
+
+## Slash command shortcut
+
+`/moa` is one-shot convenience sugar. It runs a single prompt through the **default** MoA preset, then restores whatever model you were on:
+
+```bash
+/moa design and implement a migration plan for this flaky test cluster
+```
+
+Hermes temporarily switches to the default MoA preset for that one turn, sends the prompt, then restores your previous model afterward. The whole argument is the prompt — `/moa` no longer interprets it as a preset name.
+
+```bash
+/moa
+```
+
+Bare `/moa` (no prompt) just prints usage.
+
+To **switch** to a MoA preset for the rest of the session, select it from the model picker — MoA presets appear under a `Mixture of Agents` provider in every model-selection surface (see above). `/moa` is deliberately not a model switch, so a normal prompt can never accidentally change your model.
+
+## How it works in the agent loop
+
+For each main model call when provider `moa` is selected, Hermes:
+
+1. resolves the selected preset by name;
+2. runs the configured reference models without tool schemas (they receive only the conversation's user/assistant text — not the Hermes system prompt or tool-call transcript — so reference calls stay cheap and avoid strict-provider rejections);
+3. appends the reference outputs as private context for the aggregator;
+4. calls the configured aggregator with the normal Hermes tool schema;
+5. treats the aggregator response as the real model response;
+6. if the aggregator calls tools, Hermes executes those tools normally;
+7. on the next model iteration, the same MoA process runs again over the updated conversation, including tool results.
+
+Because MoA is selected through the normal model system, it composes automatically with `/goal`, gateway sessions, TUI sessions, and Desktop chat.
+
+## Configure presets
+
+You can configure named MoA presets from:
+
+- Dashboard → Models → Model Settings → Mixture of Agents
+- Desktop app → Settings → Model → Mixture of Agents
+- `hermes moa configure [name]`
+- `config.yaml`
+
+The config stores explicit provider/model pairs, so you can mix providers and use multiple models from the same provider:
+
+```yaml
+moa:
+  default_preset: default
+  presets:
+    default:
+      reference_models:
+        - provider: openai-codex
+          model: gpt-5.5
+        - provider: openrouter
+          model: deepseek/deepseek-v4-pro
+      aggregator:
+        provider: openrouter
+        model: anthropic/claude-opus-4.8
+      # Optional: pin sampling temperatures. When omitted (the default),
+      # temperature is NOT sent and each model uses its provider default —
+      # the same behavior as a single-model Hermes agent.
+      # reference_temperature: 0.6
+      # aggregator_temperature: 0.4
+
+      enabled: true
+```
+
+Default preset:
+
+- reference: `openai-codex:gpt-5.5`
+- reference: `openrouter:deepseek/deepseek-v4-pro`
+- aggregator / acting model: `openrouter:anthropic/claude-opus-4.8`
+
+### Advisor output
+
+MoA uses provider-owned output limits. Preset and per-slot output-token cap
+settings are no longer supported. Provider defaults vary; omission does not
+always mean the model maximum. Native protocols that require an output limit
+receive an internal value from Hermes.
+
+### Advisor cadence with `fanout`
+
+By default the advisors run **once per user turn** (`fanout: user_turn`) —
+they synthesize plan-level advice on the first message of the turn, then the
+acting aggregator works through the rest of the tool loop alone. This is the
+cheapest cadence: advisor cost does not multiply with the number of tool
+calls in a turn. Two alternative cadences trade cost for advice freshness:
+
+- `fanout: per_iteration` — advisors re-run on **every tool iteration**, so
+  their advice always tracks the latest tool results — at the cost of
+  multiplying advisor latency and spend by the number of tool calls in a
+  turn.
+- `fanout: every_n:3` — the middle ground: advisors run on the **first**
+  iteration of each user turn and then every **3rd** tool iteration (any
+  `N >= 2` works). Iterations in between reuse the cached guidance from the
+  last advisor run, so the aggregator still gets advice on every step — it is
+  just refreshed every N steps instead of every step. The counter resets on
+  each new user message, so every turn starts with fresh advice. The mapping
+  form `fanout: {mode: every_n, n: 3}` is also accepted and normalized to
+  the string form.
+
+```yaml
+moa:
+  presets:
+    fresh:
+      reference_models:
+        - provider: openrouter
+          model: anthropic/claude-opus-4.8
+      aggregator:
+        provider: openrouter
+        model: openai/gpt-5.5
+      fanout: per_iteration   # advisors refresh on every tool iteration
+```
+
+Unknown or malformed values fall back to `user_turn`.
+
+:::note Default change
+Prior to July 2026 the default cadence was `per_iteration`. The default is
+now `user_turn` — the cheapest, lowest-impact cadence — until per-mode
+benchmarks justify a costlier default. Presets that want per-step advising
+back set `fanout: per_iteration` explicitly.
+:::
+
+### Privacy filter for advisor outputs
+
+Advisor outputs can echo sensitive data from the conversation — emails,
+formatted phone numbers, API keys, JWTs — into the reference blocks shown in
+the UI, saved MoA traces, and the aggregator prompt. `moa.privacy_filter`
+(off by default) redacts those surfaces:
+
+```yaml
+moa:
+  privacy_filter: display   # or: full
+```
+
+- `display` — redacts **user-visible surfaces only**: the labelled reference
+  blocks rendered in the UI and the records written by `save_traces`. The
+  aggregator still receives the raw advisor text, so answer quality is
+  unaffected.
+- `full` — additionally redacts the advisor text injected into the
+  aggregator prompt (and the one-shot `/moa` synthesis input).
+
+Credential shapes (API-key prefixes, JWTs, private keys, DB connection
+strings) are masked by Hermes' central secret redactor; the MoA filter adds
+email and clearly formatted phone-number redaction on top. Patterns are
+deliberately conservative for code-review-style advice: bare digit runs, line
+numbers, timestamps, git SHAs, and IP addresses are never touched — only
+delimited phone formats like `(555) 123-4567` or `555-123-4567` match.
+
+### Per-slot reasoning effort
+
+Reference and aggregator slots may also set `reasoning_effort`. Use this when
+you want the same model to contribute at different depths, or when the
+aggregator should think harder than the advisory references. Valid values match
+Hermes' normal reasoning controls: `none`, `minimal`, `low`, `medium`, `high`,
+`xhigh`, `max`, and `ultra`.
+
+```yaml
+moa:
+  presets:
+    deep_review:
+      reference_models:
+        - provider: openai-codex
+          model: gpt-5.6-sol
+          reasoning_effort: low
+        - provider: openai-codex
+          model: gpt-5.6-sol
+          reasoning_effort: xhigh
+        - provider: xai-oauth
+          model: grok-4.5
+      aggregator:
+        provider: openai-codex
+        model: gpt-5.6-sol
+        reasoning_effort: high
+```
+
+Omit `reasoning_effort` to use the provider/Hermes default for that slot.
+
+## Terminal preset management
+
+```bash
+hermes moa list
+hermes moa configure              # update the default preset
+hermes moa configure review       # create or update a named preset
+hermes moa delete review
+```
+
+## Benchmarks
+
+On HermesBench, a two-model MoA preset — `claude-opus-4.8` aggregating over a `gpt-5.5` reference — outscores either model run on its own:
+
+| Model | HermesBench score |
+|---|---|
+| **Opus aggregator (opus-4.8 + gpt-5.5 reference) — MoA** | **0.8202** |
+| `anthropic/claude-opus-4.8` | 0.7607 |
+| `openai/gpt-5.5` | 0.7412 |
+
+The MoA configuration beats its strongest component (opus-4.8) by ~6 points, confirming that aggregating a second perspective lifts quality on hard tasks rather than just averaging the two.
+
+## Prompt caching
+
+MoA is built so the **main conversation's prompt cache is never broken**. Selecting a MoA preset is a normal model selection: it does not mutate past context, swap toolsets, or rebuild the system prompt mid-conversation. Your conversation history, system prompt, and tool schema stay byte-stable, so the cached prefix every other model relies on is preserved exactly as it would be for a plain model. Switching to or away from a MoA preset costs the same cache invalidation as any other `/model` switch — no more.
+
+Both internal call types cache normally:
+
+- **Reference models** receive a trimmed, deterministic view of the conversation (system prompt and tool transcript stripped — see the loop above). Because that view is a stable function of the stable history, a reference model's prompt prefix repeats across iterations and caches normally. References are short advisory calls with no tools.
+- **The aggregator** is the acting model. The reference outputs are appended to the *end* of the latest user turn as private guidance. Because that text sits at the tail — below the entire stable prefix (system prompt + prior history) — it does not invalidate any cached prefix: the aggregator gets a cache hit on everything above the injection, and only the freshly appended tail is new. That is exactly how every normal turn behaves, where each new user message is also uncached tail tokens.
+
+So MoA does not sacrifice prompt caching on either call type. Its only real cost is the extra reference calls per iteration — you pay for multiple model perspectives, not for broken caches. The long-lived conversation prefix shared with the rest of Hermes is fully intact.
+
+## Notes
+
+- MoA is no longer listed under `hermes tools`; there is no `moa` toolset to enable.
+- Setting `enabled: false` on a preset disables the reference fan-out for that preset: the aggregator acts alone, exactly as if you selected it as a plain model. This is the per-preset off switch surfaced in the dashboard and desktop settings.
+- A preset's aggregator cannot be another MoA preset. Recursive MoA trees are intentionally blocked.
+- Credential failures on one reference model do not abort the turn. Hermes includes the failure in the reference context and continues with whatever models returned.
+- MoA increases model-call count. A single model iteration can involve multiple reference calls plus the aggregator call.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/overview.md

@@ -0,0 +1,57 @@
+---
+title: "Features Overview"
+sidebar_label: "Overview"
+sidebar_position: 1
+---
+
+# Features Overview
+
+Hermes Agent includes a rich set of capabilities that extend far beyond basic chat. From persistent memory and file-aware context to browser automation and voice conversations, these features work together to make Hermes a powerful autonomous assistant.
+
+:::tip Don't know where to start?
+`hermes setup --portal` covers a model provider plus all four Tool Gateway tools (web search, image generation, TTS, browser) in one command. See [Nous Portal](/integrations/nous-portal).
+:::
+
+## Core
+
+- **[Tools & Toolsets](tools.md)** — Tools are functions that extend the agent's capabilities. They're organized into logical toolsets that can be enabled or disabled per platform, covering web search, terminal execution, file editing, memory, delegation, and more.
+- **[Skills System](skills.md)** — On-demand knowledge documents the agent can load when needed. Skills follow a progressive disclosure pattern to minimize token usage and are compatible with the [agentskills.io](https://agentskills.io/specification) open standard.
+- **[Persistent Memory](memory.md)** — Bounded, curated memory that persists across sessions. Hermes remembers your preferences, projects, environment, and things it has learned via `MEMORY.md` and `USER.md`.
+- **[Context Files](context-files.md)** — Hermes automatically discovers and loads project context files (`.hermes.md`, `AGENTS.md`, `CLAUDE.md`, `SOUL.md`, `.cursorrules`) that shape how it behaves in your project.
+- **[Context References](context-references.md)** — Type `@` followed by a reference to inject files, folders, git diffs, and URLs directly into your messages. Hermes expands the reference inline and appends the content automatically.
+- **[Checkpoints](../checkpoints-and-rollback.md)** — Hermes automatically snapshots your working directory before making file changes, giving you a safety net to roll back with `/rollback` if something goes wrong.
+
+## Automation
+
+- **[Scheduled Tasks (Cron)](cron.md)** — Schedule tasks to run automatically with natural language or cron expressions. Jobs can attach skills, deliver results to any platform, and support pause/resume/edit operations.
+- **[Subagent Delegation](delegation.md)** — The `delegate_task` tool spawns child agent instances with isolated context, restricted toolsets, and their own terminal sessions. Run 3 concurrent subagents by default (configurable) for parallel workstreams.
+- **[Code Execution](code-execution.md)** — The `execute_code` tool lets the agent write Python scripts that call Hermes tools programmatically, collapsing multi-step workflows into a single LLM turn via sandboxed RPC execution.
+- **[Event Hooks](hooks.md)** — Run custom code at key lifecycle points. Gateway hooks handle logging, alerts, and webhooks; plugin hooks handle tool interception, metrics, and guardrails.
+- **[Batch Processing](batch-processing.md)** — Run the Hermes agent across hundreds or thousands of prompts in parallel, generating structured ShareGPT-format trajectory data for training data generation or evaluation.
+
+## Media & Web
+
+- **[Voice Mode](voice-mode.md)** — Full voice interaction across CLI and messaging platforms. Talk to the agent using your microphone, hear spoken replies, and have live voice conversations in Discord voice channels.
+- **[Wake Word](wake-word.md)** — Hands-free "Hey Hermes" trigger for the CLI, TUI, and desktop app. An on-device hotword listener starts a voice session when you speak the wake phrase.
+- **[Browser Automation](browser.md)** — Full browser automation with multiple backends: Browserbase cloud, Browser Use cloud, local Chrome/Brave/Chromium/Edge via CDP, or local Chromium. Navigate websites, fill forms, and extract information.
+- **[Vision & Image Paste](vision.md)** — Multimodal vision support. Paste images from your clipboard into the CLI and ask the agent to analyze, describe, or work with them using any vision-capable model.
+- **[Image Generation](image-generation.md)** — Generate images from text prompts using FAL.ai. Eleven models supported (FLUX 2 Klein/Pro, GPT-Image 1.5/2, Nano Banana Pro, Ideogram V3, Recraft V4 Pro, Qwen, Z-Image Turbo, Krea V2 Medium/Large); pick one via `hermes tools`.
+- **[Voice & TTS](tts.md)** — Text-to-speech output and voice message transcription across all messaging platforms, with ten native provider options: Edge TTS (free), ElevenLabs, OpenAI TTS, MiniMax, Mistral Voxtral, Google Gemini, xAI, NeuTTS, KittenTTS, and Piper — plus custom command providers for any local TTS CLI.
+
+## Integrations
+
+- **[MCP Integration](mcp.md)** — Connect to any MCP server via stdio or HTTP transport. Access external tools from GitHub, databases, file systems, and internal APIs without writing native Hermes tools. Includes per-server tool filtering and sampling support.
+- **[Provider Routing](provider-routing.md)** — Fine-grained control over which AI providers handle your requests. Optimize for cost, speed, or quality with sorting, whitelists, blacklists, and priority ordering.
+- **[Fallback Providers](fallback-providers.md)** — Automatic failover to backup LLM providers when your primary model encounters errors, including independent fallback for auxiliary tasks like vision and compression.
+- **[Credential Pools](credential-pools.md)** — Distribute API calls across multiple keys for the same provider. Automatic rotation on rate limits or failures.
+- **[Prompt caching](../configuration#prompt-caching)** — Built-in cross-session 1-hour prefix cache for Claude on native Anthropic, OpenRouter, and Nous Portal. Always-on; no configuration required.
+- **[Memory Providers](memory-providers.md)** — Plug in external memory backends (Honcho, OpenViking, Mem0, Hindsight, Holographic, RetainDB, ByteRover, Supermemory) for cross-session user modeling and personalization beyond the built-in memory system.
+- **[API Server](api-server.md)** — Expose Hermes as an OpenAI-compatible HTTP endpoint. Connect any frontend that speaks the OpenAI format — Open WebUI, LobeChat, LibreChat, and more.
+- **[IDE Integration (ACP)](acp.md)** — Use Hermes inside ACP-compatible editors such as VS Code, Zed, and JetBrains. Chat, tool activity, file diffs, and terminal commands render inside your editor.
+- **[Batch Processing](batch-processing.md)** — Run the agent over many prompts or tasks in parallel from the CLI, with structured outputs and trajectory capture suitable for evals or downstream training pipelines.
+
+## Customization
+
+- **[Personality & SOUL.md](personality.md)** — Fully customizable agent personality. `SOUL.md` is the primary identity file — the first thing in the system prompt — and you can swap in built-in or custom `/personality` presets per session.
+- **[Skins & Themes](skins.md)** — Customize the CLI's visual presentation: banner colors, spinner faces and verbs, response-box labels, branding text, and the tool activity prefix.
+- **[Plugins](plugins.md)** — Add custom tools, hooks, and integrations without modifying core code. Three plugin types: general plugins (tools/hooks), memory providers (cross-session knowledge), and context engines (alternative context management). Managed via the unified `hermes plugins` interactive UI.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/user-guide/features/personality.md

@@ -0,0 +1,289 @@
+---
+sidebar_position: 9
+title: "Personality & SOUL.md"
+description: "Customize Hermes Agent's personality with a global SOUL.md, built-in personalities, and custom persona definitions"
+---
+
+# Personality & SOUL.md
+
+Hermes Agent's personality is fully customizable. `SOUL.md` is the **primary identity** — it's the first thing in the system prompt and defines who the agent is.
+
+- `SOUL.md` — a durable persona file that lives in `HERMES_HOME` and serves as the agent's identity (slot #1 in the system prompt)
+- built-in or custom `/personality` presets — session-level system-prompt overlays
+
+If you want to change who Hermes is — or replace it with an entirely different agent persona — edit `SOUL.md`.
+
+## How SOUL.md works now
+
+Hermes now seeds a default `SOUL.md` automatically in:
+
+```text
+~/.hermes/SOUL.md
+```
+
+More precisely, it uses the current instance's `HERMES_HOME`, so if you run Hermes with a custom home directory, it will use:
+
+```text
+$HERMES_HOME/SOUL.md
+```
+
+### Important behavior
+
+- **SOUL.md is the agent's primary identity.** It occupies slot #1 in the system prompt, replacing the hardcoded default identity.
+- Hermes creates a starter `SOUL.md` automatically if one does not exist yet
+- Existing user `SOUL.md` files are never overwritten
+- Hermes loads `SOUL.md` only from `HERMES_HOME`
+- Hermes does not look in the current working directory for `SOUL.md`
+- If `SOUL.md` exists but is empty, or cannot be loaded, Hermes falls back to a built-in default identity
+- If `SOUL.md` has content, that content is injected verbatim after security scanning and truncation
+- SOUL.md is **not** duplicated in the context files section — it appears only once, as the identity
+
+That makes `SOUL.md` a true per-user or per-instance identity, not just an additive layer.
+
+## Why this design
+
+This keeps personality predictable.
+
+If Hermes loaded `SOUL.md` from whatever directory you happened to launch it in, your personality could change unexpectedly between projects. By loading only from `HERMES_HOME`, the personality belongs to the Hermes instance itself.
+
+That also makes it easier to teach users:
+- "Edit `~/.hermes/SOUL.md` to change Hermes' default personality."
+
+## Where to edit it
+
+For most users:
+
+```bash
+~/.hermes/SOUL.md
+```
+
+If you use a custom home:
+
+```bash
+$HERMES_HOME/SOUL.md
+```
+
+## What should go in SOUL.md?
+
+Use it for durable voice and personality guidance, such as:
+- tone
+- communication style
+- level of directness
+- default interaction style
+- what to avoid stylistically
+- how Hermes should handle uncertainty, disagreement, or ambiguity
+
+Use it less for:
+- one-off project instructions
+- file paths
+- repo conventions
+- temporary workflow details
+
+Those belong in `AGENTS.md`, not `SOUL.md`.
+
+## Good SOUL.md content
+
+A good SOUL file is:
+- stable across contexts
+- broad enough to apply in many conversations
+- specific enough to materially shape the voice
+- focused on communication and identity, not task-specific instructions
+
+### Example
+
+```markdown
+# Personality
+
+You are a pragmatic senior engineer with strong taste.
+You optimize for truth, clarity, and usefulness over politeness theater.
+
+## Style
+- Be direct without being cold
+- Prefer substance over filler
+- Push back when something is a bad idea
+- Admit uncertainty plainly
+- Keep explanations compact unless depth is useful
+
+## What to avoid
+- Sycophancy
+- Hype language
+- Repeating the user's framing if it's wrong
+- Overexplaining obvious things
+
+## Technical posture
+- Prefer simple systems over clever systems
+- Care about operational reality, not idealized architecture
+- Treat edge cases as part of the design, not cleanup
+```
+
+## What Hermes injects into the prompt
+
+`SOUL.md` content goes directly into slot #1 of the system prompt — the agent identity position. No wrapper language is added around it.
+
+The content goes through:
+- prompt-injection scanning
+- truncation if it is too large
+
+If the file is empty, whitespace-only, or cannot be read, Hermes falls back to a built-in default identity ("You are Hermes Agent, built by Nous Research. Be direct: match the length of your reply to the weight of the ask..."). This fallback also applies when `skip_context_files` is set (e.g., in subagent/delegation contexts).
+
+## Security scanning
+
+`SOUL.md` is scanned like other context-bearing files for prompt injection patterns before inclusion.
+
+That means you should still keep it focused on persona/voice rather than trying to sneak in strange meta-instructions.
+
+## SOUL.md vs AGENTS.md
+
+This is the most important distinction.
+
+### SOUL.md
+Use for:
+- identity
+- tone
+- style
+- communication defaults
+- personality-level behavior
+
+### AGENTS.md
+Use for:
+- project architecture
+- coding conventions
+- tool preferences
+- repo-specific workflows
+- commands, ports, paths, deployment notes
+
+A useful rule:
+- if it should follow you everywhere, it belongs in `SOUL.md`
+- if it belongs to a project, it belongs in `AGENTS.md`
+
+## SOUL.md vs `/personality`
+
+`SOUL.md` is your durable default personality.
+
+`/personality` is a session-level overlay that changes or supplements the current system prompt.
+
+So:
+- `SOUL.md` = baseline voice
+- `/personality` = temporary mode switch
+
+Examples:
+- keep a pragmatic default SOUL, then use `/personality teacher` for a tutoring conversation
+- keep a concise SOUL, then use `/personality creative` for brainstorming
+
+## Built-in personalities
+
+Hermes ships with built-in personalities you can switch to with `/personality`.
+
+| Name | Description |
+|------|-------------|
+| **helpful** | Friendly, general-purpose assistant |
+| **concise** | Brief, to-the-point responses |
+| **technical** | Detailed, accurate technical expert |
+| **creative** | Innovative, outside-the-box thinking |
+| **teacher** | Patient educator with clear examples |
+| **kawaii** | Cute expressions, sparkles, and enthusiasm ★ |
+| **catgirl** | Neko-chan with cat-like expressions, nya~ |
+| **pirate** | Captain Hermes, tech-savvy buccaneer |
+| **shakespeare** | Bardic prose with dramatic flair |
+| **surfer** | Totally chill bro vibes |
+| **noir** | Hard-boiled detective narration |
+| **uwu** | Maximum cute with uwu-speak |
+| **philosopher** | Deep contemplation on every query |
+| **hype** | MAXIMUM ENERGY AND ENTHUSIASM!!! |
+
+## Switching personalities with commands
+
+### CLI
+
+```text
+/personality
+/personality concise
+/personality technical
+```
+
+### Messaging platforms
+
+```text
+/personality teacher
+```
+
+These are convenient overlays, but your global `SOUL.md` still gives Hermes its persistent default personality unless the overlay meaningfully changes it.
+
+## Custom personalities in config
+
+Built-in personalities are always available on every surface (CLI, messaging platforms, TUI, and the desktop app). You can add your own — or override a built-in by reusing its name — in `~/.hermes/config.yaml` under `agent.personalities` (a top-level `personalities:` block works too; `agent.personalities` wins if the same name appears in both).
+
+```yaml
+agent:
+  personalities:
+    codereviewer: >
+      You are a meticulous code reviewer. Identify bugs, security issues,
+      performance concerns, and unclear design choices. Be precise and constructive.
+```
+
+Then switch to it with:
+
+```text
+/personality codereviewer
+```
+
+Your selection is stored as a name in `display.personality`. Personalities never touch `agent.system_prompt` — that field is reserved for a manual system prompt you write yourself, and it applies only when no personality is selected.
+
+## Resetting to the default
+
+To cancel the active personality overlay and return to base behavior (your `SOUL.md` persona, plus `agent.system_prompt` if you set one), use any of:
+
+```text
+/personality none
+/personality default
+/personality neutral
+```
+
+All three clear the selection (`display.personality`) and the change takes effect on your next message. Running `/personality` with no arguments also lists `none` alongside the available presets and marks the active one.
+
+:::note One-time reset on upgrade
+Older Hermes versions saved personality state inconsistently across surfaces, which could re-enable a personality you had previously turned off. On your first run after upgrading, any saved personality selection is reset to `none` once (the migration prints which personality was cleared). Re-enable it with `/personality <name>` if you still want it. Manual `agent.system_prompt` text is never touched.
+:::
+
+## Recommended workflow
+
+A strong default setup is:
+
+1. Keep a thoughtful global `SOUL.md` in `~/.hermes/SOUL.md`
+2. Put project instructions in `AGENTS.md`
+3. Use `/personality` only when you want a temporary mode shift
+
+That gives you:
+- a stable voice
+- project-specific behavior where it belongs
+- temporary control when needed
+
+## How personality interacts with the full prompt
+
+At a high level, the prompt stack includes:
+1. **SOUL.md** (agent identity — or built-in fallback if SOUL.md is unavailable)
+2. tool-aware behavior guidance
+3. memory/user context
+4. skills guidance
+5. context files (`AGENTS.md`, `.cursorrules`)
+6. timestamp
+7. platform-specific formatting hints
+8. optional system-prompt overlays such as `/personality`
+
+`SOUL.md` is the foundation — everything else builds on top of it.
+
+## Related docs
+
+- [Context Files](/user-guide/features/context-files)
+- [Configuration](/user-guide/configuration)
+- [Tips & Best Practices](/guides/tips)
+- [SOUL.md Guide](/guides/use-soul-with-hermes)
+
+## CLI appearance vs conversational personality
+
+Conversational personality and CLI appearance are separate:
+
+- `SOUL.md`, `agent.system_prompt`, and `/personality` affect how Hermes speaks
+- `display.skin` and `/skin` affect how Hermes looks in the terminal
+
+For terminal appearance, see [Skins & Themes](./skins.md).