diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 36b182750..97ee94eb4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -217,6 +217,27 @@ Breaking changes map to the `type:breaking-change` label.
 
 ---
 
+## Hermes — Knowledge-Layer Agent
+
+Hermes is a detect-only agent in the Gentle-AI ecosystem. Unlike coding agents (Claude Code, OpenCode, Cursor), Hermes cannot be auto-installed by Gentle-AI, but once installed manually it can still be configured (skills injection, `SOUL.md` section injection, and YAML MCP config merge under `~/.hermes/`). Hermes does not support subagents.
+
+### Capabilities
+
+- **SOUL.md system prompt** — injected via `StrategyMarkdownSections`, which uses marker-based insertion into existing prompt files.
+- **YAML MCP config** — injected via `StrategyMergeIntoYAML`, which merges MCP server blocks into `config.yaml` without overwriting user configuration outside the managed MCP block.
+- **Skills directory** — skill files are written to `~/.hermes/skills/` (SDD suite + optional skills).
+
+### Why It Matters
+
+Hermes's YAML MCP strategy is the reference implementation for non-coding agents that need MCP configuration. If you are building a knowledge-layer integration (MCP servers for context, memory, or retrieval), Hermes's YAML merge strategy is the adapter pattern to follow. It demonstrates how to inject MCP configuration into a YAML-structured config file using comment-preserving, hand-rolled helpers (not a full YAML AST round-trip) and without overwriting user content outside managed blocks.
+
+### Contributing
+
+- Hermes cannot be auto-installed. It must be installed manually before Gentle-AI detects it.
+- Adapter location: `internal/agents/hermes/adapter.go`
+- `Tier()` returns `TierFull` (tier is metadata for display purposes), but `SupportsAutoInstall()` remains `false` — there is no auto-install path.
+- No subagents, no slash commands, no output styles.
+
 ## Branch Naming
 
 Branch names **must** match this pattern:
diff --git a/README.md b/README.md
index c81a5d49b..d35fc5f60 100644
--- a/README.md
+++ b/README.md
@@ -44,7 +44,7 @@ Gentle-AI is NOT an AI agent installer. Most agents are easy to install. It is a
 | **OpenClaw**        |            Solo-agent            | Workspace-first `AGENTS.md` / `SOUL.md` with global MCP config  |
 | **Trae**            |            Solo-agent            | Desktop app by ByteDance; `~/.trae/skills/` + OS-specific rules |
 | **Pi**              | Full (package-managed subagents) | `gentle-pi` harness with persona/model commands + Engram memory |
-| **Hermes**          |         Detect-only              | YAML MCP config, SOUL.md persona; install manually first        |
+| **Hermes**          |         Detect-only              | Knowledge-layer agent — YAML MCP config via `StrategyMergeIntoYAML`, `SOUL.md` persona; install manually first |
 
 > **Note**: This project supersedes [Agent Teams Lite](https://github.com/Gentleman-Programming/agent-teams-lite) (now archived). Everything ATL provided is included here with better installation, automatic updates, and persistent memory.