docs: move Hermes overview out of agent context root

[Michaelyklam]

Thinking Path

• Hermes Agent gives root HERMES.md / .hermes.md higher project-context priority than AGENTS.md.
• This repository's root HERMES.md is a long human-facing overview/comparison document, while AGENTS.md is the assistant-facing contributor guidance.
• The safest repository-side fix is to move the overview into docs/ and keep root free of Hermes context filenames.
• A small regression test makes the constraint explicit so the root filename does not come back accidentally.

What Changed

• Moved HERMES.md to docs/why-hermes.md.
• Updated README references to the new docs path.
• Added tests/test_agent_context_docs.py to assert root HERMES.md / .hermes.md do not exist and the README links the moved document.
• Added an Unreleased changelog entry.

Why It Matters

• Hermes Agent sessions in this repository now load AGENTS.md as the project-specific assistant guidance instead of the long product-positioning document.
• The human-facing comparison doc remains published and linked from README.
• Future contributors get a clear test failure if a root Hermes context file would shadow AGENTS.md again.

Verification

• env -u HERMES_CONFIG_PATH -u HERMES_WEBUI_HOST /home/michael/.hermes/hermes-agent/venv/bin/python -m pytest tests/test_agent_context_docs.py -q — 2 passed
• git diff --check

Risks / Follow-ups

• This is a docs-path move, so external links to root HERMES.md may need updating if any exist outside this repository.
• No runtime or UI behavior changes.

Closes #2595

Model Used

AI-assisted change with repository inspection, targeted editing, and shell-based test verification.

[nesquena-hermes]

Summary

Read the PR diff on 471b75d7 plus issue #2595 and the agent-side selection logic in ~/.hermes/hermes-agent/agent/prompt_builder.py. The fix is correct, narrowly scoped, and addresses the actual contract that was wrong.

Code reference (agent side, confirming the contract)

The selection priority at agent/prompt_builder.py:1449-1454 is exactly what the issue claimed:

project_context = (
    _load_hermes_md(cwd_path)
    or _load_agents_md(cwd_path)
    or _load_claude_md(cwd_path)
    or _load_cursorrules(cwd_path)
)

And the filename set at agent/prompt_builder.py:89:

_HERMES_MD_NAMES = (".hermes.md", "HERMES.md")

First-match-wins, with HERMES.md ahead of AGENTS.md. With the repo previously carrying a 489-line / 28kB HERMES.md at root, that file shadowed AGENTS.md for every Hermes Agent session opened against the WebUI checkout, injecting ~4k tokens of product-positioning copy into the system prompt and hiding the actual contributor guidance that lives in AGENTS.md. The fix is the right shape: move the doc to docs/why-hermes.md so the agent walks past the missing root file and picks up AGENTS.md, while the human-facing comparison remains published and linked from README.md.

Diagnosis

The agent walks cwd then parents up to the git root looking for _HERMES_MD_NAMES. Putting the file under docs/ means a session started with cwd = ~/hermes-webui finds no HERMES.md at ~/hermes-webui/ or at any parent, falls through to _load_agents_md, and now picks up AGENTS.md (which is what was always intended). A session started inside docs/ would also walk parents and miss the moved file — and that is fine, because docs/why-hermes.md is not in _HERMES_MD_NAMES regardless of directory.

Test coverage

The regression test at tests/test_agent_context_docs.py pins both halves of the contract:

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/."
        )

Good — that asserts the negative invariant (no root HERMES.md or .hermes.md) which is exactly what the agent contract requires. The README-link test at the same file pins the published-document side so the doc cannot silently get orphaned by a future rename.

Recommendation

Approve. The change is the minimum repository-side action that fixes #2595, the test pins the constraint so a future contributor cannot accidentally reintroduce a root context file, and there is no runtime behavior change (this is docs-and-test only). The CHANGELOG entry under Unreleased is appropriate. README link updates at lines 71, 92, and 555 all flip to docs/why-hermes.md, which I verified in the diff.

One small note: if you ever want WebUI-specific Hermes Agent operational guidance (i.e. an actual HERMES.md that complements rather than shadows AGENTS.md), a future PR could add a short root HERMES.md whose body just @-includes AGENTS.md plus a couple of WebUI-specific notes. That would satisfy the agent contract (HERMES.md found, project context loaded) while keeping the practical content unified. Not blocking this PR — just a possible future direction once the long marketing document is safely under docs/.