From 471b75d76232cb9d5910550149cac63dc0631a30 Mon Sep 17 00:00:00 2001 From: Michael Lam Date: Tue, 19 May 2026 23:55:04 -0700 Subject: [PATCH] docs: move Hermes overview out of agent context root --- CHANGELOG.md | 3 +++ README.md | 6 +++--- HERMES.md => docs/why-hermes.md | 0 tests/test_agent_context_docs.py | 21 +++++++++++++++++++++ 4 files changed, 27 insertions(+), 3 deletions(-) rename HERMES.md => docs/why-hermes.md (100%) create mode 100644 tests/test_agent_context_docs.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 185f15f1..01d590fa 100644 --- a/CHANGELOG.md +++ b/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) diff --git a/README.md b/README.md index e2d50a7c..f0074e2b 100644 --- a/README.md +++ b/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 diff --git a/HERMES.md b/docs/why-hermes.md similarity index 100% rename from HERMES.md rename to docs/why-hermes.md diff --git a/tests/test_agent_context_docs.py b/tests/test_agent_context_docs.py new file mode 100644 index 00000000..6072eec9 --- /dev/null +++ b/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