Feat/readme curation refresh 20260312

.github/PULL_REQUEST_TEMPLATE.md

@@ -7,6 +7,13 @@
 - [ ] The project is actively maintained
 - [ ] The entry is in alphabetical order within its section
 
+## Merge + Hygiene Checklist
+
+- [ ] Branch is up to date with `main` (rebased or merged) before review
+- [ ] No conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) remain
+- [ ] CI checks pass (link check/docs health)
+- [ ] Scope is tight (no unrelated files or drive-by edits)
+
 ### Entry
 
 ```markdown

.github/scripts/check_internal_links.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python3
+
+import os
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path('.')
+
+MD_FILES = []
+for path in ROOT.rglob('*.md'):
+    if '.git' in path.parts:
+        continue
+    MD_FILES.append(path)
+
+existing = {p.as_posix() for p in MD_FILES}
+
+link_pattern = re.compile(r'\[[^\]]+\]\(([^)]+)\)')
+fence_pattern = re.compile(r'```.*?```', re.DOTALL)
+inline_code_pattern = re.compile(r'`[^`]*`')
+
+errors = []
+
+for md_file in MD_FILES:
+    text = md_file.read_text(encoding='utf-8', errors='ignore')
+
+    # Ignore fenced and inline code so examples like [Name](URL) do not fail.
+    text = fence_pattern.sub('', text)
+    text = inline_code_pattern.sub('', text)
+
+    for match in link_pattern.finditer(text):
+        raw = match.group(1).strip()
+
+        if raw.startswith(('http://', 'https://', 'mailto:', '#')):
+            continue
+
+        if raw.startswith('<') and raw.endswith('>'):
+            raw = raw[1:-1]
+
+        raw = raw.split('#', 1)[0].split('?', 1)[0]
+        if not raw or raw.startswith(('/', 'javascript:')):
+            continue
+
+        target = (md_file.parent / raw).resolve()
+        try:
+            rel_target = target.relative_to(ROOT.resolve()).as_posix()
+        except ValueError:
+            errors.append((md_file.as_posix(), raw, 'path escapes repository root'))
+            continue
+
+        if rel_target in existing:
+            continue
+
+        if not target.exists():
+            errors.append((md_file.as_posix(), raw, rel_target))
+
+if errors:
+    print('Broken internal markdown links found:\n')
+    for source, raw, resolved in errors:
+        print(f'- {source}: ({raw}) -> {resolved}')
+    print(f'\nTotal broken internal links: {len(errors)}')
+    sys.exit(1)
+
+print(f'OK: checked {len(MD_FILES)} markdown files, no broken internal links.')

.github/workflows/docs-health.yml

@@ -0,0 +1,29 @@
+name: Docs Health
+
+on:
+  pull_request:
+    paths:
+      - '**/*.md'
+      - '.github/scripts/check_internal_links.py'
+      - '.github/workflows/docs-health.yml'
+  push:
+    branches: [main]
+    paths:
+      - '**/*.md'
+      - '.github/scripts/check_internal_links.py'
+      - '.github/workflows/docs-health.yml'
+
+jobs:
+  internal-links:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Check internal markdown links
+        run: python .github/scripts/check_internal_links.py

.github/workflows/link-check.yml

@@ -37,5 +37,5 @@ jobs:
             --exclude 'https://cursor.directory.*'
             --exclude 'https://spec.modelcontextprotocol.io.*'
             --exclude 'https://platform.openai.com/docs/.*'
-            README.md guides/**/*.md claude/**/*.md
+            README.md guides/**/*.md claude/**/*.md hermes/**/*.md codex/**/*.md cursorrules/**/*.md CONTRIBUTING.md CODE_OF_CONDUCT.md
           fail: true

hermes/05-production-profiles.md

@@ -0,0 +1,108 @@
+# Hermes Production Profiles
+
+Copy/paste deployment profiles for common operating modes.
+
+Assumptions:
+- Hermes installed and on PATH
+- `~/.hermes/config.yaml` and `~/.hermes/.env` exist
+- API/provider credentials already set
+
+## Profile A: Local Dev (fastest feedback)
+
+Use when:
+- you are iterating on prompts/skills/workflows
+- low isolation risk (trusted repos and commands)
+
+Suggested settings:
+- terminal backend: local
+- cwd: current project
+- shorter timeout for tight loops
+
+Baseline steps:
+
+```bash
+hermes model
+hermes tools
+hermes config set terminal.backend local
+hermes
+```
+
+Operational notes:
+- best ergonomics and speed
+- least isolation; avoid unknown scripts/repos
+
+## Profile B: VPS Operator (24/7 remote agent)
+
+Use when:
+- you want always-on automation
+- you need durable remote sessions + gateway access
+
+Suggested settings:
+- run Hermes on a dedicated VM user
+- systemd/tmux for process continuity
+- cron jobs for recurring maintenance and reports
+
+Baseline flow:
+
+```bash
+hermes setup
+hermes gateway
+hermes doctor
+```
+
+Operational notes:
+- enable least-privilege Linux user
+- route secrets via environment file only
+- back up `~/.hermes/` regularly
+
+## Profile C: Isolated Execution (higher safety)
+
+Use when:
+- untrusted repos or risky command surfaces
+- regulated workflows requiring stronger boundaries
+
+Suggested settings:
+- terminal backend: docker/ssh/singularity
+- explicit workspace root restrictions
+- conservative toolset selection
+
+Baseline flow:
+
+```bash
+hermes config set terminal.backend docker
+hermes tools
+hermes doctor
+```
+
+Operational notes:
+- slower than local, but safer
+- validate mounted paths and writable scope
+
+## Profile D: Messaging-First Ops (chat-native control plane)
+
+Use when:
+- operating mostly from Telegram/Discord/Slack/etc.
+- asynchronous command-and-control workflows
+
+Suggested settings:
+- gateway enabled and monitored
+- clear MESSAGING_CWD policy
+- notification and alert routing defined
+
+Baseline flow:
+
+```bash
+hermes gateway
+```
+
+Operational notes:
+- treat messaging channels as production interfaces
+- apply strict access controls and chat authorization rules
+
+## Security baseline for all profiles
+
+- never commit `.env`
+- keep dangerous-command approval on
+- run `hermes doctor` after config changes
+- keep weekly memory/skill hygiene review cadence
+- log automation outputs to durable artifacts when possible

hermes/06-runtime-comparison-matrix.md

@@ -0,0 +1,48 @@
+# Hermes Runtime Comparison Matrix
+
+High-level operator comparison for commonly used agent runtimes.
+Purpose: quick routing and stack selection, not absolute ranking.
+
+## Scope
+
+Compared stacks:
+- Hermes Agent
+- Claude Code
+- OpenAI Codex CLI
+- OpenHands
+- Goose
+
+## Matrix (operator view)
+
+| Dimension | Hermes Agent | Claude Code | Codex CLI | OpenHands | Goose |
+|---|---|---|---|---|---|
+| Primary mode | General autonomous agent runtime | Coding-focused CLI agent | Coding-focused CLI agent | SWE automation platform | Dev-agent CLI/runtime |
+| Built-in persistent memory model | Yes (memory + user profile) | Limited/session-oriented memory files | Limited/session-oriented | Platform/task oriented | Varies by setup |
+| Skill/procedural memory system | Yes (first-class skills lifecycle) | Prompt/memory workflows | Prompt/workflow patterns | Repo task workflows | Tool/workflow oriented |
+| Multi-platform messaging gateway | Yes | No | No | Not primary focus | Not primary focus |
+| Built-in cron/scheduling | Yes | No | No | External orchestration | External orchestration |
+| Subagent delegation | Yes | Pattern-based | Pattern-based | Multi-agent task patterns | Pattern-based |
+| Tool extensibility breadth | Broad (toolsets + MCP + terminal/file/web/browser/etc.) | Strong coding/tool loop | Strong coding/tool loop | Strong for SWE automation | Strong for dev workflows |
+| Best-fit use case | Always-on personal/company operator agent | Interactive code tasks in repo | Interactive code tasks in repo | End-to-end software task execution | Terminal-native dev automation |
+
+## Decision heuristics
+
+Choose Hermes when you need:
+- one runtime spanning CLI + messaging + automation
+- durable memory and reusable procedural skills
+- scheduled autonomous operations with delivery targets
+
+Choose coding-first stacks when you mainly need:
+- direct repo-centric code generation/refactor/debug loops
+- minimal non-coding orchestration requirements
+
+## Hybrid pattern that works well
+
+- Hermes as control plane (memory, scheduling, multi-channel interface)
+- coding-focused agents as specialized executors per task
+
+This gives you broad operational continuity plus high-velocity code execution.
+
+## Caveat
+
+Feature sets evolve rapidly. Re-check official docs before committing to long-term architecture decisions.

hermes/07-operator-checklists.md

@@ -0,0 +1,77 @@
+# Hermes Operator Checklists
+
+Practical recurring checklists for reliability and quality.
+
+## Daily checklist (10-15 min)
+
+1) Runtime health
+- `hermes doctor`
+- confirm active provider/model still healthy
+
+2) Automation health
+- review recent scheduled job outputs
+- verify no silent failures/timeouts
+
+3) Memory hygiene (light)
+- capture only high-signal learnings
+- avoid noisy/trivial memory writes
+
+4) Security quick pass
+- verify no secrets in tracked files
+- verify approval policy still enabled
+
+## Weekly checklist (30-45 min)
+
+1) Memory compaction review
+- identify stale/redundant memory items
+- produce recommendation plan first
+- require explicit approval before deletions
+
+2) Skills maintenance
+- inspect recently used skills
+- patch stale steps/paths/assumptions
+- add one new skill from repeated workflows
+
+3) Config drift review
+- compare current config against desired baseline
+- verify terminal backend and cwd policy
+
+4) Reliability review
+- scan recent tool failures
+- convert recurring failures into documented runbooks
+
+## Monthly checklist (60-90 min)
+
+1) Dependency/runtime review
+- update Hermes and supporting dependencies
+- run full diagnostics after upgrade
+
+2) Workflow benchmark
+- test representative tasks end-to-end
+- document latency, failure patterns, intervention rate
+
+3) Security and privacy review
+- rotate sensitive credentials as needed
+- review message platform permissions and access
+
+4) Architecture review
+- confirm current profile (local/vps/isolated/messaging-first)
+- adjust stack split between control-plane and executor agents
+
+## Incident checklist (when things break)
+
+1) Stop automation blast radius
+- disable or pause risky cron jobs
+
+2) Collect evidence
+- command logs, tool outputs, config snapshot
+
+3) Reproduce minimally
+- isolate failing task in smallest possible environment
+
+4) Fix and verify
+- implement minimal patch
+- rerun target workflow + diagnostics
+
+5) Learn
+- write/update skill or runbook so issue becomes non-recurring