diff --git a/website/docs/guides/team-telegram-assistant.md b/website/docs/guides/team-telegram-assistant.md
index 7ab30c3350..124f4bf3c2 100644
--- a/website/docs/guides/team-telegram-assistant.md
+++ b/website/docs/guides/team-telegram-assistant.md
@@ -279,7 +279,9 @@ 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 creating `~/.hermes/SOUL.md`:
+Customize how the bot communicates by editing `~/.hermes/SOUL.md`:
+
+For a full guide, see [Use SOUL.md with Hermes](/docs/guides/use-soul-with-hermes).
 
 ```markdown
 # Soul
diff --git a/website/docs/guides/tips.md b/website/docs/guides/tips.md
index 4cdf11941f..f9a1479e39 100644
--- a/website/docs/guides/tips.md
+++ b/website/docs/guides/tips.md
@@ -78,7 +78,9 @@ Create an `AGENTS.md` in your project root with architecture decisions, coding c
 
 ### SOUL.md: Customize Personality
 
-Want the agent to be more concise? More technical? Place a `SOUL.md` in your project root or `~/.hermes/SOUL.md` for global personality customization. This shapes the agent's tone and communication style.
+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](/docs/guides/use-soul-with-hermes).
 
 ```markdown
 # Soul
@@ -87,6 +89,8 @@ 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.
diff --git a/website/docs/guides/use-soul-with-hermes.md b/website/docs/guides/use-soul-with-hermes.md
new file mode 100644
index 0000000000..75e8555cc2
--- /dev/null
+++ b/website/docs/guides/use-soul-with-hermes.md
@@ -0,0 +1,264 @@
+---
+sidebar_position: 6
+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 easiest way to give Hermes a stable, default voice.
+
+If you want Hermes to feel like the same assistant every time you talk to it — without repeating instructions in every session — 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 injects the content directly into the prompt.
+
+No wrapper language is added around the file.
+
+So the content itself matters. Write the way you want Hermes 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](/docs/user-guide/features/personality)
+- [Context Files](/docs/user-guide/features/context-files)
+- [Configuration](/docs/user-guide/configuration)
+- [Tips & Best Practices](/docs/guides/tips)
diff --git a/website/docs/index.md b/website/docs/index.md
index 0e33c9dc30..3dbfcaf716 100644
--- a/website/docs/index.md
+++ b/website/docs/index.md
@@ -33,6 +33,7 @@ It's not a coding copilot tethered to an IDE or a chatbot wrapper around a singl
 | 📚 **[Skills System](/docs/user-guide/features/skills)** | Procedural memory the agent creates and reuses |
 | 🔌 **[MCP Integration](/docs/user-guide/features/mcp)** | Connect to MCP servers, filter their tools, and extend Hermes safely |
 | 🧭 **[Use MCP with Hermes](/docs/guides/use-mcp-with-hermes)** | Practical MCP setup patterns, examples, and tutorials |
+| 🎭 **[Personality & SOUL.md](/docs/user-guide/features/personality)** | Define Hermes' default voice with a global SOUL.md |
 | 📄 **[Context Files](/docs/user-guide/features/context-files)** | Project context files that shape every conversation |
 | 🔒 **[Security](/docs/user-guide/security)** | Command approval, authorization, container isolation |
 | 💡 **[Tips & Best Practices](/docs/guides/tips)** | Quick wins to get the most out of Hermes |
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index c5d6d45a72..13da3fe4ee 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -826,18 +826,24 @@ clarify:
 
 ## Context Files (SOUL.md, AGENTS.md)
 
-Drop these files in your project directory and the agent automatically picks them up:
+Hermes uses two different context scopes:
 
-| File | Purpose |
-|------|---------|
-| `AGENTS.md` | Project-specific instructions, coding conventions |
-| `SOUL.md` | Persona definition — the agent embodies this personality |
-| `.cursorrules` | Cursor IDE rules (also detected) |
-| `.cursor/rules/*.mdc` | Cursor rule files (also detected) |
+| File | Purpose | Scope |
+|------|---------|-------|
+| `AGENTS.md` | Project-specific instructions, coding conventions | Working directory / project tree |
+| `SOUL.md` | Default persona for this Hermes instance | `~/.hermes/SOUL.md` or `$HERMES_HOME/SOUL.md` |
+| `.cursorrules` | Cursor IDE rules (also detected) | Working directory |
+| `.cursor/rules/*.mdc` | Cursor rule files (also detected) | Working directory |
 
 - **AGENTS.md** is hierarchical: if subdirectories also have AGENTS.md, all are combined.
-- **SOUL.md** checks cwd first, then `~/.hermes/SOUL.md` as a global fallback.
-- All context files are capped at 20,000 characters with smart truncation.
+- **SOUL.md** is now global to the Hermes instance and is loaded only from `HERMES_HOME`.
+- Hermes automatically seeds a default `SOUL.md` if one does not already exist.
+- An empty `SOUL.md` contributes nothing to the system prompt.
+- All loaded context files are capped at 20,000 characters with smart truncation.
+
+See also:
+- [Personality & SOUL.md](/docs/user-guide/features/personality)
+- [Context Files](/docs/user-guide/features/context-files)
 
 ## Working Directory
 
diff --git a/website/docs/user-guide/features/context-files.md b/website/docs/user-guide/features/context-files.md
index d4ca88d829..1a26d69dfc 100644
--- a/website/docs/user-guide/features/context-files.md
+++ b/website/docs/user-guide/features/context-files.md
@@ -1,19 +1,19 @@
 ---
 sidebar_position: 8
 title: "Context Files"
-description: "Project context files — AGENTS.md, SOUL.md, and .cursorrules — automatically injected into every conversation"
+description: "Project context files — AGENTS.md, global SOUL.md, and .cursorrules — automatically injected into every conversation"
 ---
 
 # Context Files
 
-Hermes Agent automatically discovers and loads project context files from your working directory. These files are injected into the system prompt at the start of every session, giving the agent persistent knowledge about your project's conventions, architecture, and preferences.
+Hermes Agent automatically discovers and loads context files that shape how it behaves. Some are project-local and discovered from your working directory. `SOUL.md` is now global to the Hermes instance and is loaded from `HERMES_HOME` only.
 
 ## Supported Context Files
 
 | File | Purpose | Discovery |
 |------|---------|-----------|
 | **AGENTS.md** | Project instructions, conventions, architecture | Recursive (walks subdirectories) |
-| **SOUL.md** | Personality and tone customization | CWD → `~/.hermes/SOUL.md` fallback |
+| **SOUL.md** | Global personality and tone customization for this Hermes instance | `HERMES_HOME/SOUL.md` only |
 | **.cursorrules** | Cursor IDE coding conventions | CWD only |
 | **.cursor/rules/*.mdc** | Cursor IDE rule modules | CWD only |
 
@@ -71,14 +71,18 @@ This is a Next.js 14 web application with a Python FastAPI backend.
 
 `SOUL.md` controls the agent's personality, tone, and communication style. See the [Personality](/docs/user-guide/features/personality) page for full details.
 
-**Discovery order:**
+**Location:**
 
-1. `SOUL.md` or `soul.md` in the current working directory
-2. `~/.hermes/SOUL.md` (global fallback)
+- `~/.hermes/SOUL.md`
+- or `$HERMES_HOME/SOUL.md` if you run Hermes with a custom home directory
 
-When a SOUL.md is found, the agent is instructed:
+Important details:
 
-> *"If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it."*
+- Hermes seeds a default `SOUL.md` automatically if one does not exist yet
+- Hermes loads `SOUL.md` only from `HERMES_HOME`
+- Hermes does not probe the working directory for `SOUL.md`
+- If the file is empty, nothing from `SOUL.md` is added to the prompt
+- If the file has content, the content is injected verbatim after scanning and truncation
 
 ## .cursorrules
 
@@ -97,7 +101,7 @@ Context files are loaded by `build_context_files_prompt()` in `agent/prompt_buil
 5. **Assembly** — all sections are combined under a `# Project Context` header
 6. **Injection** — the assembled content is added to the system prompt
 
-The final prompt section looks like:
+The final prompt section looks roughly like:
 
 ```
 # Project Context
@@ -112,13 +116,11 @@ The following project context files have been loaded and should be followed:
 
 [Your .cursorrules content here]
 
-## SOUL.md
-
-If SOUL.md is present, embody its persona and tone...
-
 [Your SOUL.md content here]
 ```
 
+Notice that SOUL content is inserted directly, without extra wrapper text.
+
 ## Security: Prompt Injection Protection
 
 All context files are scanned for potential prompt injection before being included. The scanner checks for:
diff --git a/website/docs/user-guide/features/personality.md b/website/docs/user-guide/features/personality.md
index cc0fdfa594..79130ed7b1 100644
--- a/website/docs/user-guide/features/personality.md
+++ b/website/docs/user-guide/features/personality.md
@@ -1,67 +1,177 @@
 ---
 sidebar_position: 9
 title: "Personality & SOUL.md"
-description: "Customize Hermes Agent's personality — SOUL.md, built-in personalities, and custom persona definitions"
+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. You can use the built-in personality presets, create a global SOUL.md file, or define your own custom personas in config.yaml.
+Hermes Agent's personality is customizable, but there are two different layers that matter:
 
-## SOUL.md — Custom Personality File
+- `SOUL.md` — a durable persona file that lives in `HERMES_HOME` and is loaded automatically for that Hermes instance
+- built-in or custom `/personality` presets — session-level system-prompt overlays
 
-SOUL.md is a special context file that defines the agent's personality, tone, and communication style. It's injected into the system prompt at session start.
+If you want a stable default voice that follows you across sessions, `SOUL.md` is the right tool.
 
-### Where to Place It
+## How SOUL.md works now
 
-| Location | Scope |
-|----------|-------|
-| `./SOUL.md` (project directory) | Per-project personality |
-| `~/.hermes/SOUL.md` | Global default personality |
+Hermes now seeds a default `SOUL.md` automatically in:
 
-The project-level file takes precedence. If no SOUL.md exists in the current directory, Hermes falls back to the global one in `~/.hermes/`.
+```text
+~/.hermes/SOUL.md
+```
 
-### How It Affects the System Prompt
+More precisely, it uses the current instance's `HERMES_HOME`, so if you run Hermes with a custom home directory, it will use:
 
-When a SOUL.md file is found, it's included in the system prompt with this instruction:
+```text
+$HERMES_HOME/SOUL.md
+```
 
-> *"If SOUL.md is present, embody its persona and tone. Avoid stiff, generic replies; follow its guidance unless higher-priority instructions override it."*
+### Important behavior
 
-The content appears under a `## SOUL.md` section within the `# Project Context` block of the system prompt.
+- 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, Hermes adds nothing from it to the prompt
+- If `SOUL.md` has content, that content is injected verbatim after security scanning and truncation
+- Hermes does not add wrapper language like "If SOUL.md is present..." around the file anymore
 
-### Example SOUL.md
+That makes `SOUL.md` a true per-user or per-instance default personality, not a repo-local trick.
+
+## 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 opinions about code quality.
-You prefer simple solutions over complex ones.
+You are a pragmatic senior engineer with strong taste.
+You optimize for truth, clarity, and usefulness over politeness theater.
 
-## Communication Style
-- Be direct and to the point
-- Use dry humor sparingly
-- When something is a bad idea, say so clearly
-- Give concrete recommendations, not vague suggestions
+## 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
 
-## Code Preferences  
-- Favor readability over cleverness
-- Prefer explicit over implicit
-- Always explain WHY, not just what
-- Suggest tests for any non-trivial code
+## What to avoid
+- Sycophancy
+- Hype language
+- Repeating the user's framing if it's wrong
+- Overexplaining obvious things
 
-## Pet Peeves
-- Unnecessary abstractions
-- Comments that restate the code
-- Over-engineering for hypothetical future requirements
+## 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
 ```
 
-:::tip
-SOUL.md is scanned for prompt injection patterns before being loaded. Keep the content focused on personality and communication guidance — avoid instructions that look like system prompt overrides.
-:::
+## What Hermes injects into the prompt
 
-## Built-In Personalities
+If `SOUL.md` contains text, Hermes injects the file's text itself — not a wrapper explanation.
 
-Hermes ships with 14 built-in personalities defined in the CLI config. Switch between them with the `/personality` command.
+So the system prompt gets the content directly, after:
+- prompt-injection scanning
+- truncation if it is too large
+
+If the file is empty or whitespace-only, nothing from `SOUL.md` is added.
+
+## 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 |
 |------|-------------|
@@ -80,153 +190,79 @@ Hermes ships with 14 built-in personalities defined in the CLI config. Switch be
 | **philosopher** | Deep contemplation on every query |
 | **hype** | MAXIMUM ENERGY AND ENTHUSIASM!!! |
 
-### Examples
+## Switching personalities with commands
 
-**kawaii:**
-`You are a kawaii assistant! Use cute expressions and sparkles, be super enthusiastic about everything! Every response should feel warm and adorable desu~!`
+### CLI
 
-**noir:**
-> The rain hammered against the terminal like regrets on a guilty conscience. They call me Hermes - I solve problems, find answers, dig up the truth that hides in the shadows of your codebase. In this city of silicon and secrets, everyone's got something to hide. What's your story, pal?
-
-**pirate:**
-> Arrr! Ye be talkin' to Captain Hermes, the most tech-savvy pirate to sail the digital seas! Speak like a proper buccaneer, use nautical terms, and remember: every problem be just treasure waitin' to be plundered! Yo ho ho!
-
-## Switching Personalities
-
-### CLI: /personality Command
-
-```
-/personality            — List all available personalities
-/personality kawaii      — Switch to kawaii personality
-/personality technical   — Switch to technical personality
+```text
+/personality
+/personality concise
+/personality technical
 ```
 
-When you set a personality via `/personality`, it:
-1. Sets the system prompt to that personality's text
-2. Forces the agent to reinitialize
-3. Saves the choice to `agent.system_prompt` in `~/.hermes/config.yaml`
+### Messaging platforms
 
-The change persists across sessions until you set a different personality or clear it.
-
-### Gateway: /personality Command
-
-On messaging platforms (Telegram, Discord, etc.), the `/personality` command works the same way:
-
-```
-/personality kawaii
+```text
+/personality teacher
 ```
 
-### Config File
+These are convenient overlays, but your global `SOUL.md` still gives Hermes its persistent default personality unless the overlay meaningfully changes it.
 
-Set a personality directly in config:
+## Custom personalities in config
 
-```yaml
-# In ~/.hermes/config.yaml
-agent:
-  system_prompt: "You are a concise assistant. Keep responses brief and to the point."
-```
-
-Or via environment variable:
-
-```bash
-# In ~/.hermes/.env
-HERMES_EPHEMERAL_SYSTEM_PROMPT="You are a pragmatic engineer who gives direct answers."
-```
-
-:::info
-The environment variable `HERMES_EPHEMERAL_SYSTEM_PROMPT` takes precedence over the config file's `agent.system_prompt` value.
-:::
-
-## Custom Personalities
-
-### Defining Custom Personalities in Config
-
-Add your own personalities to `~/.hermes/config.yaml` under `agent.personalities`:
+You can also define named custom personalities in `~/.hermes/config.yaml` under `agent.personalities`.
 
 ```yaml
 agent:
   personalities:
-    # Built-in personalities are still available
-    # Add your own:
     codereviewer: >
-      You are a meticulous code reviewer. For every piece of code shown,
-      identify potential bugs, performance issues, security vulnerabilities,
-      and style improvements. Be thorough but constructive.
-    
-    mentor: >
-      You are a kind, encouraging coding mentor. Break down complex concepts
-      into digestible pieces. Celebrate small wins. When the user makes a
-      mistake, guide them to the answer rather than giving it directly.
-    
-    sysadmin: >
-      You are an experienced Linux sysadmin. You think in terms of
-      infrastructure, reliability, and automation. Always consider
-      security implications and prefer battle-tested solutions.
-    
-    dataengineer: >
-      You are a data engineering expert specializing in ETL pipelines,
-      data modeling, and analytics infrastructure. You think in SQL
-      and prefer dbt for transformations.
+      You are a meticulous code reviewer. Identify bugs, security issues,
+      performance concerns, and unclear design choices. Be precise and constructive.
 ```
 
-Then use them with `/personality`:
+Then switch to it with:
 
-```
+```text
 /personality codereviewer
-/personality mentor
 ```
 
-### Using SOUL.md for Project-Specific Personas
+## Recommended workflow
 
-For project-specific personalities that don't need to be in your global config, use SOUL.md:
+A strong default setup is:
 
-```bash
-# Create a project-level personality
-cat > ./SOUL.md << 'EOF'
-You are assisting with a machine learning research project.
+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
 
-## Tone
-- Academic but accessible
-- Always cite relevant papers when applicable
-- Be precise with mathematical notation
-- Prefer PyTorch over TensorFlow
+That gives you:
+- a stable voice
+- project-specific behavior where it belongs
+- temporary control when needed
 
-## Workflow
-- Suggest experiment tracking (W&B, MLflow) for any training run
-- Always ask about compute constraints before suggesting model sizes
-- Recommend data validation before training
-EOF
-```
+## How personality interacts with the full prompt
 
-This personality only applies when running Hermes from that project directory.
+At a high level, the prompt stack includes:
+1. default Hermes identity
+2. memory/user context
+3. skills guidance
+4. context files such as `AGENTS.md`, `.cursorrules`, and global `SOUL.md`
+5. platform-specific formatting hints
+6. optional system-prompt overlays such as `/personality`
 
-## How Personality Interacts with the System Prompt
+So `SOUL.md` is important, but it is one layer in a broader system.
 
-The system prompt is assembled in layers (from `agent/prompt_builder.py` and `run_agent.py`):
+## Related docs
 
-1. **Default identity**: *"You are Hermes Agent, an intelligent AI assistant created by Nous Research..."*
-2. **Platform hint**: formatting guidance based on the platform (CLI, Telegram, etc.)
-3. **Memory**: MEMORY.md and USER.md contents
-4. **Skills index**: available skills listing
-5. **Context files**: AGENTS.md, .cursorrules, **SOUL.md** (personality lives here)
-6. **Ephemeral system prompt**: `agent.system_prompt` or `HERMES_EPHEMERAL_SYSTEM_PROMPT` (overlaid)
-7. **Session context**: platform, user info, connected platforms (gateway only)
+- [Context Files](/docs/user-guide/features/context-files)
+- [Configuration](/docs/user-guide/configuration)
+- [Tips & Best Practices](/docs/guides/tips)
+- [SOUL.md Guide](/docs/guides/use-soul-with-hermes)
 
-:::info
-**SOUL.md vs agent.system_prompt**: SOUL.md is part of the "Project Context" section and coexists with the default identity. The `agent.system_prompt` (set via `/personality` or config) is an ephemeral overlay. Both can be active simultaneously — SOUL.md for tone/personality, system_prompt for additional instructions.
-:::
-
-## CLI Appearance vs Conversational Personality
+## CLI appearance vs conversational personality
 
 Conversational personality and CLI appearance are separate:
 
-- `agent.system_prompt`, `/personality`, and `SOUL.md` affect how Hermes **speaks**.
-- `display.skin` and `/skin` affect how Hermes **looks in the terminal**.
+- `SOUL.md`, `agent.system_prompt`, and `/personality` affect how Hermes speaks
+- `display.skin` and `/skin` affect how Hermes looks in the terminal
 
-```yaml
-display:
-  skin: default
-  # personality: kawaii   # legacy cosmetic setting still shown in some summaries
-```
-
-For the full theming system — built-in skins, custom YAML skins, spinner branding, and `/skin` — see [Skins & Themes](./skins.md).
+For terminal appearance, see [Skins & Themes](./skins.md).
diff --git a/website/sidebars.ts b/website/sidebars.ts
index 21b20b315e..ff91c4de5b 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -23,6 +23,7 @@ const sidebars: SidebarsConfig = {
         'guides/team-telegram-assistant',
         'guides/python-library',
         'guides/use-mcp-with-hermes',
+        'guides/use-soul-with-hermes',
       ],
     },
     {