docs: move Hermes overview out of agent context root

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+### Documentation
+
+- **PR #2619** by @Michaelyklam (closes #2595) — Move the long human-facing Hermes comparison document from root `HERMES.md` to `docs/why-hermes.md` so Hermes Agent sessions in this repository load `AGENTS.md` as the project-specific assistant guidance. README links now point to the new docs path and a regression test prevents root `HERMES.md` / `.hermes.md` context files from shadowing `AGENTS.md` again.
 
 ## [v0.51.95] — 2026-05-20 — Release BS (stage-388 — 5-PR batch — live tool callback event dedup + browser-only dashboard links + messaging transcript merge alignment + Geist Contrast skin + SSE runtime diagnostics)
 

README.md

@@ -68,7 +68,7 @@ What makes it different from other agentic tools:
   the results back into its own memory
 - **Self-hosted** — your conversations, your memory, your hardware
 
-**vs. the field** *(landscape is actively shifting — see [HERMES.md](HERMES.md) for the full breakdown)*:
+**vs. the field** *(landscape is actively shifting — see [docs/why-hermes.md](docs/why-hermes.md) for the full breakdown)*:
 
 | | OpenClaw | Claude Code | Codex CLI | OpenCode | Hermes |
 |---|---|---|---|---|---|
@@ -89,7 +89,7 @@ with memory, cron, and messaging. The key differences: Hermes writes and saves i
 automatically as a core behavior (OpenClaw's skill system centers on a community marketplace);
 Hermes is more stable across updates (OpenClaw has documented release regressions and ClawHub
 has had security incidents involving malicious skills); and Hermes runs natively in the Python
-ecosystem. See [HERMES.md](HERMES.md) for the full side-by-side.
+ecosystem. See [docs/why-hermes.md](docs/why-hermes.md) for the full side-by-side.
 
 ---
 
@@ -552,7 +552,7 @@ State lives outside the repo at `~/.hermes/webui/` by default
 
 ## Docs
 
-- `HERMES.md` -- why Hermes, mental model, and detailed comparison to Claude Code / Codex / OpenCode / Cursor
+- `docs/why-hermes.md` -- why Hermes, mental model, and detailed comparison to Claude Code / Codex / OpenCode / Cursor
 - `ROADMAP.md` -- feature roadmap and sprint history
 - `ARCHITECTURE.md` -- system design, all API endpoints, implementation notes
 - `TESTING.md` -- manual browser test plan and automated coverage reference

tests/test_agent_context_docs.py

@@ -0,0 +1,21 @@
+from pathlib import Path
+
+
+def test_root_does_not_shadow_agents_md_with_hermes_context_file():
+    repo_root = Path(__file__).resolve().parents[1]
+
+    for name in ("HERMES.md", ".hermes.md"):
+        assert not (repo_root / name).exists(), (
+            f"{name} at the repository root is auto-loaded by Hermes Agent as "
+            "project context before AGENTS.md; long human-facing Hermes overview "
+            "docs belong under docs/."
+        )
+
+
+def test_why_hermes_doc_remains_linked_from_readme():
+    repo_root = Path(__file__).resolve().parents[1]
+    readme = (repo_root / "README.md").read_text(encoding="utf-8")
+
+    assert (repo_root / "docs" / "why-hermes.md").exists()
+    assert "docs/why-hermes.md" in readme
+    assert "[HERMES.md](HERMES.md)" not in readme