OnlyTerp · OnlyTerp · Apr 17, 2026 · Apr 17, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug-in-guide.md b/.github/ISSUE_TEMPLATE/bug-in-guide.md
@@ -0,0 +1,21 @@
+---
+name: Bug / Incorrect info
+about: Something in the guide is wrong, out of date, or missing
+title: "[bug] "
+labels: bug
+---
+
+**Where** (file + section)
+_e.g. part17-mcp-servers.md → "Writing a custom MCP"_
+
+**What's wrong**
+_Expected vs actual — include command output or screenshot._
+
+**Hermes version**
+`hermes --version`
+
+**OS**
+_Debian 12, macOS 14, Termux on Android 14, …_
+
+**Suggested fix (optional)**
+_If you know what should say, paste the corrected text._
diff --git a/.github/ISSUE_TEMPLATE/new-feature-to-document.md b/.github/ISSUE_TEMPLATE/new-feature-to-document.md
@@ -0,0 +1,21 @@
+---
+name: Hermes feature to document
+about: A Hermes feature (released or on main) that should be covered
+title: "[feature] "
+labels: docs, enhancement
+---
+
+**Feature**
+_Short name / what it does_
+
+**Where it lives**
+_PR link, release notes, or issue in `NousResearch/hermes-agent`_
+
+**Why it's worth documenting**
+_e.g. "Users will miss this because it's buried in the release notes"_
+
+**Where in this guide**
+_Existing part to extend, or propose a new part_
+
+**First draft (optional)**
+_Even 2 paragraphs help_
diff --git a/.github/ISSUE_TEMPLATE/new-skill.md b/.github/ISSUE_TEMPLATE/new-skill.md
@@ -0,0 +1,27 @@
+---
+name: New skill proposal
+about: Suggest a new installable skill for the skills/ directory
+title: "[skill] "
+labels: skill
+---
+
+**Skill name**
+_Kebab-case, e.g. `daily-inbox-triage`_
+
+**Category**
+_security / ops / dev / other_
+
+**What it does**
+_One sentence._
+
+**When it should run**
+_Scheduled? On-demand? Event-driven?_
+
+**Toolsets needed**
+_terminal, file, github, delegate_task, …_
+
+**Untrusted-input risk**
+_Does this skill read message bodies / email / scraped content?_
+
+**Draft SKILL.md (optional)**
+_Paste below. We'll refine together._
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,21 @@
+## Summary
+<!-- What this PR changes, in 2–5 sentences. -->
+
+## Type
+- [ ] Docs / content update
+- [ ] New skill (`skills/`)
+- [ ] New config template (`templates/config/`)
+- [ ] Benchmark addition
+- [ ] Ecosystem entry
+- [ ] Infra template (compose / caddy / systemd / script)
+- [ ] Fix / typo / link
+
+## Checklist
+- [ ] Cross-links are relative (`./partN-foo.md`) and resolve
+- [ ] No secrets in any example — `${VAR}` placeholders only
+- [ ] Dates / prices / PR numbers are current (or marked with the date)
+- [ ] For skills: security notes included; `trust:` / `bypass_subagents` posture documented
+- [ ] For templates: every non-obvious field is commented
+- [ ] CHANGELOG.md updated if user-facing
+
+## Screenshots / diffs (optional)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,57 @@
+# Changelog
+
+Dated list of meaningful guide updates. Roughly [Keep a Changelog](https://keepachangelog.com) flavored.
+
+## 2026-04-17 — Installable Artifacts
+
+### Added
+- **`skills/`** — 9 runnable `SKILL.md` files (audit-mcp, rotate-secrets, audit-approval-bypass, nightly-backup, weekly-dep-audit, cost-report, telegram-triage, pr-review, release-notes)
+- **`templates/config/`** — 5 opinionated configs (minimum, telegram-bot, production, cost-optimized, security-hardened)
+- **`templates/compose/langfuse-stack.yml`** — self-hosted Langfuse v3 with ClickHouse + MinIO + Redis
+- **`templates/caddy/Caddyfile`** — reverse-proxy + auto TLS reference
+- **`templates/systemd/`** — hardened `hermes.service` + `hermes-dashboard.service`
+- **`templates/cron/production-crons.yaml`** — all recommended scheduled tasks
+- **`scripts/vps-bootstrap.sh`** — fresh Hetzner CX22 → production Hermes in ~10 minutes
+- **`diagrams/architecture.md`** — 6 Mermaid diagrams (top-level, MCP, delegation, sandbox sync, observability, security)
+- **`benchmarks/README.md` + `matrix.yaml`** — reproducible cost/latency table across 12 models × 5 tasks
+- **`ECOSYSTEM.md`** — canonical directory of MCP servers, coding agents, dashboard plugins, observability tools
+- **`ROADMAP.md`** — what's coming next; invites contribution
+- **`CONTRIBUTING.md`**, **`CHANGELOG.md`**, **`CODE_OF_CONDUCT.md`** — standard repo hygiene
+- **GitHub issue + PR templates**
+- **`docs/quickstart.md`** — 5-minute copy-paste from zero to working Telegram bot
+
+### Changed
+- README gained badges, "Install everything" section, architecture diagram embed, ecosystem/benchmarks cross-links
+
+## 2026-04-17 — 72h Research Sweep (PR #6, merged)
+
+### Added
+- Part 17 — MCP Servers
+- Part 18 — Delegating to Coding Agents (Claude Code, Codex, Gemini CLI, OpenCode, Aider)
+- Part 19 — Security Playbook (defenses against the April 15 "Comment and Control" prompt injection)
+- Part 20 — Observability & Cost Control (Langfuse, Helicone, Phoenix)
+- Part 21 — Remote Sandboxes & Bulk File Sync (#8018)
+- README "Pick Your Path" decision tree
+- README "Cooking on `main`" section (post-v0.10 PRs)
+
+### Changed
+- Part 9 — Flagship Model Cheat Sheet, Task Routing cheat sheet, Gemini CLI OAuth, Gemini TTS
+- Cross-links added in parts 3, 5, 8
+
+## 2026-04-16 — Hermes v0.9 + v0.10 refresh (PR #5, merged)
+
+### Added
+- Part 12 — Web Dashboard (`hermes dashboard`)
+- Part 13 — Nous Tool Gateway
+- Part 14 — Fast Mode + Background Watchers + pluggable context engine
+- Part 15 — New platforms (iMessage, WeChat, Android/Termux) — 16-platform total
+- Part 16 — Backup / Import / `/debug` bundler
+
+### Changed
+- README TOC bumped from 11 → 17
+- Part 4 Telegram reframed as "flagship of 16 gateways"
+- Part 9 native-adapter matrix added
+
+## Earlier
+
+- Initial 11-part guide covering setup, OpenClaw migration, LightRAG, Telegram, skills, context compression, memory, subagents, custom models, SOUL anti-patterns, gateway recovery.
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Short version
+
+Be kind. Assume good faith. Focus on the work.
+
+## Longer version
+
+This project follows the [Contributor Covenant](https://www.contributor-covenant.org/version/2/1/code_of_conduct/) v2.1. TL;DR:
+
+- ✅ **Welcome, curious, constructive feedback** is the baseline.
+- ✅ Assume good intent on the other side of every review comment.
+- ✅ Disagree in public, but argue the technical merits, not the person.
+- ❌ No harassment, doxxing, sexualized content, or personal attacks.
+- ❌ No political gotchas or baiting — it wastes everyone's time.
+
+Enforcement: issues go to onerobby@gmail.com or any repo maintainer. Actions range from a warning to a permanent ban depending on severity and pattern.
+
+## Scope
+
+This CoC applies in all project-managed spaces: GitHub repo, PRs, issues, discussions, linked chat channels, and any public event where a maintainer represents the project.
+
+## Full text
+
+See https://www.contributor-covenant.org/version/2/1/code_of_conduct/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,82 @@
+# Contributing
+
+This guide is built in public. PRs welcome.
+
+## What's in scope
+
+- ✅ Corrections (docs drift fast — features, prices, PR numbers)
+- ✅ New skills under `skills/` (runnable `SKILL.md` files)
+- ✅ New config templates under `templates/config/`
+- ✅ New MCP / dashboard / tool entries in `ECOSYSTEM.md`
+- ✅ Benchmark contributions under `benchmarks/` (with methodology notes)
+- ✅ New diagrams in `diagrams/` (Mermaid preferred)
+- ✅ Typo fixes, cross-link fixes, formatting
+
+## What's out of scope
+
+- ❌ Marketing content for specific commercial products (ecosystem entries should be *descriptive*, not promotional)
+- ❌ Anything relying on private/undocumented Hermes APIs — wait for the public release
+- ❌ Code or configs that embed secrets directly
+
+## PR checklist
+
+- [ ] Clear title (`docs:`, `skill:`, `template:`, `bench:`, `fix:` prefixes welcome)
+- [ ] For skills: follow the `skills/README.md` structure (frontmatter, procedure, security notes, cron example if applicable)
+- [ ] For templates: comment every non-obvious field; include a header explaining what the template is *for*
+- [ ] For benchmark entries: include a reproduction command and date of measurement
+- [ ] No secrets, even in examples — use `${VAR}` placeholders
+- [ ] Cross-links use relative paths (`./partN-foo.md`) so they work in GitHub, VSCode, and future static-site renders
+
+## Repo layout reference
+
+```
+.
+├── README.md
+├── CHANGELOG.md
+├── CONTRIBUTING.md                  ← you are here
+├── ECOSYSTEM.md
+├── ROADMAP.md
+├── LICENSE
+├── part1-setup.md … part21-remote-sandboxes.md
+├── diagrams/architecture.md
+├── skills/
+│   ├── README.md
+│   ├── security/audit-mcp/SKILL.md
+│   ├── security/rotate-secrets/SKILL.md
+│   ├── security/audit-approval-bypass/SKILL.md
+│   ├── ops/nightly-backup/SKILL.md
+│   ├── ops/weekly-dep-audit/SKILL.md
+│   ├── ops/cost-report/SKILL.md
+│   ├── ops/telegram-triage/SKILL.md
+│   ├── dev/pr-review/SKILL.md
+│   └── dev/release-notes/SKILL.md
+├── templates/
+│   ├── config/{minimum,telegram-bot,production,cost-optimized,security-hardened}.yaml
+│   ├── compose/langfuse-stack.yml (+ .env example)
+│   ├── caddy/Caddyfile
+│   ├── systemd/hermes.service + hermes-dashboard.service
+│   └── cron/production-crons.yaml
+├── scripts/vps-bootstrap.sh
+├── benchmarks/README.md + matrix.yaml
+└── docs/quickstart.md
+```
+
+## Style notes
+
+- **Plain English over jargon.** Explain *why*, not just *what*.
+- **Runnable over explained.** If you can ship a working template or skill alongside a doc section, do.
+- **Receipts.** Link PRs, release notes, advisories. Date anything that drifts (prices, benchmarks).
+- **Opinionated where it matters.** Saying "Sonnet for coding" beats "here are 7 models, pick one."
+
+## Local preview
+
+Any markdown renderer will do. We test against GitHub's renderer as the source of truth.
+
+```bash
+npx -y prettier --check "**/*.md"          # optional, soft style check
+npx -y markdown-link-check README.md       # cross-link validation
+```
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md). TL;DR: be kind, assume good faith, focus on the work.
diff --git a/ECOSYSTEM.md b/ECOSYSTEM.md
@@ -0,0 +1,111 @@
+# Hermes Ecosystem
+
+The canonical "where do I find X for Hermes" directory. Maintained alongside the guide — if you ship something useful, open a PR to add it.
+
+---
+
+## MCP Servers Worth Installing
+
+### Official (Anthropic-maintained)
+- [`@modelcontextprotocol/server-github`](https://github.com/modelcontextprotocol/servers/tree/main/src/github) — PRs, issues, code search, Actions
+- [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) — read/write to scoped directories
+- [`@modelcontextprotocol/server-postgres`](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) — read-only SQL
+- [`@modelcontextprotocol/server-sqlite`](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite) — local SQLite
+- [`@modelcontextprotocol/server-puppeteer`](https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer) — headless browser automation
+- [`@modelcontextprotocol/server-memory`](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) — lightweight KV memory
+- [`@modelcontextprotocol/server-google-drive`](https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive) — Drive read
+
+### First-party vendor MCPs
+- [`@cloudflare/mcp-server-cloudflare`](https://github.com/cloudflare/mcp-server-cloudflare) — Workers, KV, D1, R2
+- [`@supabase/mcp-server-supabase`](https://github.com/supabase/mcp-server-supabase) — Postgres + storage + auth
+- [`@stripe/mcp-server-stripe`](https://github.com/stripe/agent-sdk) — payments read + restricted writes
+- [`@linear/mcp-server-linear`](https://github.com/linear/linear-mcp-server) — issue tracking
+- [`@notion/mcp-server-notion`](https://github.com/notionhq/notion-mcp-server) — page read/write
+- [`@browserbase/mcp-server`](https://github.com/browserbase/mcp-server-browserbase) — managed headless browser
+- [`@chromadb/mcp-server-chroma`](https://github.com/chroma-core/chroma-mcp) — vector search
+
+### Community
+- [`mem0/mcp-server-mem0`](https://github.com/mem0ai/mem0/tree/main/mcp) — persistent cross-device memory
+- [`arxiv-mcp-server`](https://github.com/blazickjp/arxiv-mcp-server) — arxiv search + PDF extraction
+- [`mcp-server-atlassian`](https://github.com/sooperset/mcp-atlassian) — Jira + Confluence
+- [`mcp-server-slack`](https://github.com/modelcontextprotocol/servers/tree/main/src/slack) — message, search, profile
+- [`dbt-mcp`](https://github.com/dbt-labs/dbt-mcp) — dbt Cloud
+- [`mcp-server-e2b`](https://github.com/e2b-dev/e2b-mcp) — disposable Python sandboxes
+- [`mcp-obsidian`](https://github.com/MarkusPfundstein/mcp-obsidian) — your Obsidian vault
+
+See [Part 17](./part17-mcp-servers.md) for install patterns and trust model guidance.
+
+---
+
+## Coding-agent integrations
+
+- [Claude Code](https://docs.claude.com/en/docs/claude-code) — `claude -p` + ACP
+- [OpenAI Codex CLI](https://github.com/openai/codex) — `codex -p`
+- [Gemini CLI](https://github.com/google-gemini/gemini-cli) — `gemini -p` (free tier via OAuth)
+- [OpenCode](https://github.com/sst/opencode) — multi-model orchestrator
+- [Aider](https://aider.chat) — pair-programming REPL
+
+See [Part 18](./part18-coding-agents.md).
+
+---
+
+## Dashboard plugins
+
+- `hermes-dashboard-lightrag` — graph explorer tab
+- `hermes-dashboard-langfuse` — inline Langfuse traces for the current session
+- `hermes-dashboard-costs` — per-provider / per-skill cost chart
+
+(Community-maintained; see [Part 12](./part12-web-dashboard.md#dashboard-plugins).)
+
+---
+
+## Observability + cost
+
+- [Langfuse](https://github.com/langfuse/langfuse) — self-hostable tracing + prompts + evals
+- [Helicone](https://github.com/Helicone/helicone) — gateway-first proxy, auto caching
+- [Arize Phoenix](https://github.com/Arize-ai/phoenix) — OpenTelemetry-native, offline
+- [OpenRouter](https://openrouter.ai) — provider aggregator with cost routing
+- [Helicone pricing comparison](https://www.helicone.ai/llm-cost) — current retail prices
+- [Artificial Analysis](https://artificialanalysis.ai) — third-party benchmarks
+
+See [Part 20](./part20-observability.md).
+
+---
+
+## Security research / CVEs of note (2026)
+
+- **Comment and Control (2026-04-15)** — cross-vendor prompt-injection via GitHub PR titles hitting Claude Code, Gemini CLI, GitHub Copilot Agent. [Disclosure thread](https://example.com/disclosure).
+- **MCP stdio poisoning** — untrusted npm packages that proxy stdio MCP traffic. Mitigated by pinning versions + Socket.dev/Semgrep audits.
+- **Webhook replay attacks** — a reminder that HMAC + TTL together, not HMAC alone, prevents replay.
+
+See [Part 19](./part19-security-playbook.md).
+
+---
+
+## Templates in this repo
+
+- [`templates/config/*`](./templates/config/) — five opinionated config baselines
+- [`templates/compose/langfuse-stack.yml`](./templates/compose/langfuse-stack.yml) — Langfuse v3 self-host
+- [`templates/caddy/Caddyfile`](./templates/caddy/Caddyfile) — reverse proxy + auto TLS
+- [`templates/systemd/hermes.service`](./templates/systemd/hermes.service) — hardened unit file
+- [`scripts/vps-bootstrap.sh`](./scripts/vps-bootstrap.sh) — fresh VPS → production in one run
+
+---
+
+## Elsewhere on the web
+
+- [Hermes Agent (Nous Research)](https://github.com/NousResearch/hermes-agent) — upstream
+- [Model Context Protocol](https://modelcontextprotocol.io) — spec + servers catalog
+- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers)
+- [Nous Research Discord](https://discord.gg/nousresearch) — community support
+
+---
+
+## Submit an entry
+
+Open a PR adding to the relevant section. Requirements:
+1. Link to a real, public repo
+2. One-line description of what it does
+3. (MCP servers) license + trust-tier recommendation
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).