feat: config wizard + 4 reference architectures + CI + outreach drafts + 4 new skills + i18n

.github/markdown-link-check.json

@@ -0,0 +1,22 @@
+{
+  "ignorePatterns": [
+    { "pattern": "^https://t.me/" },
+    { "pattern": "^https://example.com/" },
+    { "pattern": "^https://install.hermes.nous.ai" },
+    { "pattern": "^https://langfuse.yourdomain.com" },
+    { "pattern": "^https://hermes.yourdomain.com" },
+    { "pattern": "^https://hooks.yourdomain.com" },
+    { "pattern": "^http://localhost" },
+    { "pattern": "^http://127.0.0.1" }
+  ],
+  "httpHeaders": [
+    {
+      "urls": ["https://github.com/", "https://raw.githubusercontent.com/"],
+      "headers": { "User-Agent": "markdown-link-check" }
+    }
+  ],
+  "retryOn429": true,
+  "retryCount": 3,
+  "fallbackRetryDelay": "30s",
+  "aliveStatusCodes": [200, 206, 429, 403]
+}

.github/scripts/validate_skills.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Validate every skills/**/SKILL.md has correct frontmatter.
+
+Run via: python .github/scripts/validate_skills.py
+Exit code 0 = all pass; 1 = any fail. Each failing file is listed with reason.
+"""
+from __future__ import annotations
+
+import pathlib
+import re
+import sys
+
+import yaml
+
+REQUIRED_KEYS = {"name", "description", "when_to_use", "toolsets"}
+ALLOWED_TOOLSETS = {
+    "terminal",
+    "file",
+    "github",
+    "delegate_task",
+    "classify",
+    "telegram",
+    "web",
+    "browser",
+    "email",
+    "discord",
+    "slack",
+    "memory",
+}
+
+FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---", re.DOTALL)
+
+
+def extract_frontmatter(p: pathlib.Path) -> dict | None:
+    text = p.read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(text)
+    if not m:
+        return None
+    try:
+        return yaml.safe_load(m.group(1)) or {}
+    except yaml.YAMLError as e:
+        print(f"  yaml parse error: {e}")
+        return None
+
+
+def validate(p: pathlib.Path) -> list[str]:
+    errs: list[str] = []
+    fm = extract_frontmatter(p)
+    if fm is None:
+        return ["missing or unparseable frontmatter"]
+
+    missing = REQUIRED_KEYS - set(fm.keys())
+    if missing:
+        errs.append(f"missing required keys: {sorted(missing)}")
+
+    toolsets = fm.get("toolsets", [])
+    if not isinstance(toolsets, list):
+        errs.append("toolsets must be a list")
+    else:
+        unknown = [t for t in toolsets if t not in ALLOWED_TOOLSETS]
+        if unknown:
+            errs.append(f"unknown toolsets: {unknown} (allowed: {sorted(ALLOWED_TOOLSETS)})")
+
+    when = fm.get("when_to_use", [])
+    if not isinstance(when, list) or not when:
+        errs.append("when_to_use must be a non-empty list of triggers")
+
+    desc = fm.get("description", "")
+    if not isinstance(desc, str) or len(desc) < 10:
+        errs.append("description must be a >=10-char string")
+
+    return errs
+
+
+def main() -> int:
+    root = pathlib.Path(__file__).resolve().parents[2] / "skills"
+    if not root.is_dir():
+        print(f"::error::no skills/ dir at {root}")
+        return 1
+
+    skills = sorted(root.rglob("SKILL.md"))
+    if not skills:
+        print(f"::warning::no SKILL.md files found under {root}")
+        return 0
+
+    total_fails = 0
+    for p in skills:
+        rel = p.relative_to(root.parent)
+        errs = validate(p)
+        if errs:
+            total_fails += 1
+            print(f"::error file={rel}::{'; '.join(errs)}")
+        else:
+            print(f"ok  {rel}")
+
+    if total_fails:
+        print(f"\n{total_fails}/{len(skills)} skill(s) failed validation", file=sys.stderr)
+        return 1
+
+    print(f"\nAll {len(skills)} skill(s) passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  markdown-links:
+    name: markdown-link-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check markdown links
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          config-file: '.github/markdown-link-check.json'
+          folder-path: '.'
+          use-quiet-mode: 'yes'
+          check-modified-files-only: 'yes'
+          base-branch: 'main'
+
+  yaml-lint:
+    name: yamllint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install yamllint
+        run: pip install yamllint
+      - name: Run yamllint
+        run: yamllint -c .github/yamllint.yml templates/ benchmarks/ skills/
+
+  skill-frontmatter:
+    name: skill frontmatter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install deps
+        run: pip install pyyaml
+      - name: Validate every SKILL.md frontmatter
+        run: python .github/scripts/validate_skills.py
+
+  prettier-check:
+    name: prettier (soft)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - name: Prettier check (advisory only)
+        run: npx -y prettier --check "**/*.md" || echo "::warning::prettier formatting drift (non-blocking)"

.github/yamllint.yml

@@ -0,0 +1,26 @@
+extends: default
+
+# Goal: catch real syntax errors in template YAMLs, not formatting nits.
+# Templates often align values / use flow-mapping shorthand for cron/approval rules;
+# those are legit, so we relax those rules.
+
+rules:
+  line-length: disable
+  document-start: disable
+  comments: disable
+  comments-indentation: disable
+  colons: disable
+  commas: disable
+  indentation: disable
+  truthy:
+    allowed-values: ['true', 'false', 'on', 'off', 'yes', 'no']
+    check-keys: false
+  braces:
+    max-spaces-inside: 2
+  brackets:
+    max-spaces-inside: 2
+
+ignore: |
+  node_modules/
+  .venv/
+  templates/compose/.env.langfuse.example

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 Dated list of meaningful guide updates. Roughly [Keep a Changelog](https://keepachangelog.com) flavored.
 
+## 2026-04-17 — Wizard + Reference Architectures + CI
+
+### Added
+- **`docs/wizard/index.html`** — interactive static config wizard; 8 questions → ready-to-drop `config.yaml`, runs entirely in the browser (GitHub Pages friendly)
+- **`docs/reference-architectures/`** — 4 full blueprints: Homelab, Solo Developer, Small Agency, Road Warrior
+- **`docs/outreach/`** — launch-ready drafts: launch tweet thread, Hacker News post, r/LocalLLaMA post, upstream PR body to `NousResearch/hermes-agent`, long-form blog post
+- **4 new skills**: `ops/daily-inbox-triage`, `ops/hermes-weekly`, `security/spam-trap`, `dev/meeting-prep` (total skills: 13)
+- **CI** — `.github/workflows/ci.yml`: markdown-link-check, yamllint, skill-frontmatter validator (`validate_skills.py`), prettier advisory
+- **Localized READMEs** — [`README-zh.md`](./README-zh.md), [`README-ja.md`](./README-ja.md) (entry-level summaries)
+
+### Changed
+- README: skills badge 9→13, language links, repo map rows for wizard + reference architectures + outreach, CI badge
+- `templates/config/*.yaml` — quoted `${VAR}` env-var substitutions inside flow mappings so every template is valid YAML
+
 ## 2026-04-17 — Installable Artifacts
 
 ### Added

README-ja.md

@@ -0,0 +1,37 @@
+# Hermes 最適化ガイド（日本語ショート版）
+
+> [英語版はこちら](./README.md) · このページは入口の要約。本文の章は英語のまま。
+
+[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)（v0.10.0+）向けの実戦ガイド + インストール可能な成果物（Skills・設定テンプレ・インフラスクリプト）。
+
+## ワンコマンドで起動
+
+```bash
+# 新しい Debian 12 / Ubuntu 24.04 VPS で実行
+curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/main/scripts/vps-bootstrap.sh | sudo bash
+```
+
+もしくは [docs/quickstart.md](./docs/quickstart.md)（5 分で Telegram Bot）を参照。
+
+## 主なコンテンツ
+
+- **21 章の本文**（`part1`〜`part21`） — LightRAG、Telegram、MCP、セキュリティ、可観測性、リモートサンドボックス
+- **13 個のインストール可能 Skill**（`skills/`） — 監査、バックアップ、依存スキャン、コストレポート、Telegram トリアージ、PR レビュー、受信トレイ整理、Hermes 週報、スパムフィルタ、会議準備 など
+- **5 つのプロダクション設定テンプレ**（`templates/config/`） — minimum / telegram-bot / production / cost-optimized / security-hardened
+- **インフラ一式**（`templates/compose/`, `templates/caddy/`, `templates/systemd/`, `scripts/`） — Langfuse セルフホスト、Caddy リバースプロキシ、systemd 強化、VPS ブートストラップ
+- **Mermaid アーキテクチャ図**（`diagrams/`）
+- **再現可能なベンチマーク**（`benchmarks/`） — 12 モデル × 5 タスク、手法込み
+- **エコシステム目録**（[`ECOSYSTEM.md`](./ECOSYSTEM.md)） — MCP サーバ、コーディングエージェント、ダッシュボード拡張
+- **対話式設定ウィザード**（[`docs/wizard/`](./docs/wizard/)） — ブラウザ内で `config.yaml` を生成
+
+## 読む順番の目安
+
+1. 最速で Telegram Bot を動かしたい → [docs/quickstart.md](./docs/quickstart.md)
+2. アーキテクチャを把握したい → [diagrams/architecture.md](./diagrams/architecture.md)
+3. コストを下げたい → [part20-observability.md](./part20-observability.md) の "Cost-routing playbook"
+4. 本番運用したい → [docs/reference-architectures/](./docs/reference-architectures/) から近いものを選ぶ
+5. 公開エンドポイント → [part19-security-playbook.md](./part19-security-playbook.md) を必ず読む
+
+## ライセンス・貢献
+
+MIT。Issue / PR 歓迎。[CONTRIBUTING.md](./CONTRIBUTING.md) を参照。

README-zh.md

@@ -0,0 +1,37 @@
+# Hermes 优化指南（中文简版）
+
+> [English 完整版](./README.md) · 本页是入口摘要，章节正文仍为英文。
+
+实用指南 + 可安装制品（Skills、配置模板、基础设施脚本），针对 [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)（v0.10.0+）。
+
+## 一键起步
+
+```bash
+# 新建 Debian 12 / Ubuntu 24.04 VPS 上运行
+curl -sSL https://raw.githubusercontent.com/OnlyTerp/hermes-optimization-guide/main/scripts/vps-bootstrap.sh | sudo bash
+```
+
+或阅读 [docs/quickstart.md](./docs/quickstart.md)（5 分钟 Telegram 机器人）。
+
+## 内容一览
+
+- **21 章中文正文**（见 `part1` 到 `part21`） — LightRAG、Telegram、MCP、安全、可观测性、远程沙箱
+- **13 个可安装 Skill**（`skills/`） — 审计、备份、依赖扫描、成本报告、Telegram 分类、PR 审查、收件箱分类、Hermes 周报、垃圾过滤、会议准备 等
+- **5 套生产配置模板**（`templates/config/`） — minimum / telegram-bot / production / cost-optimized / security-hardened
+- **基础设施**（`templates/compose/`, `templates/caddy/`, `templates/systemd/`, `scripts/`） — Langfuse 自托管、Caddy 反代、systemd 硬化、VPS 引导脚本
+- **Mermaid 架构图**（`diagrams/`）
+- **可复现基准测试**（`benchmarks/`） — 12 个模型 × 5 个任务，含方法论
+- **生态目录**（[`ECOSYSTEM.md`](./ECOSYSTEM.md)） — MCP 服务器、编码代理、仪表板插件
+- **交互式配置向导**（[`docs/wizard/`](./docs/wizard/)） — 浏览器内生成 `config.yaml`
+
+## 推荐阅读顺序
+
+1. 想最快跑通 Telegram 机器人 → [docs/quickstart.md](./docs/quickstart.md)
+2. 想了解架构 → [diagrams/architecture.md](./diagrams/architecture.md)
+3. 想省钱 → [part20-observability.md](./part20-observability.md) 的 "Cost-routing playbook"
+4. 想上生产 → [docs/reference-architectures/](./docs/reference-architectures/) 选一个最接近的
+5. 用户面公开部署 → [part19-security-playbook.md](./part19-security-playbook.md) 必看
+
+## 许可与贡献
+
+MIT。欢迎 Issue / PR，详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。

README.md

@@ -4,11 +4,14 @@
 [![Hermes](https://img.shields.io/badge/Hermes-v0.10.0%20%28main%29-9146FF)](https://github.com/NousResearch/hermes-agent)
 [![Last updated](https://img.shields.io/badge/Last%20updated-2026--04--17-brightgreen)](./CHANGELOG.md)
 [![Parts](https://img.shields.io/badge/parts-21-blue)](#table-of-contents)
-[![Skills](https://img.shields.io/badge/installable%20skills-9-blue)](./skills/)
+[![Skills](https://img.shields.io/badge/installable%20skills-13-blue)](./skills/)
 [![Configs](https://img.shields.io/badge/config%20templates-5-blue)](./templates/config/)
+[![CI](https://github.com/OnlyTerp/hermes-optimization-guide/actions/workflows/ci.yml/badge.svg)](./.github/workflows/ci.yml)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 
-> **Tested on Hermes Agent v0.10.0 (v2026.4.16)** with post-release tracking for `main` · **21 parts, 9 installable skills, 5 opinionated configs, one-command VPS bootstrap** · Battle-tested on a live production deployment
+> **Tested on Hermes Agent v0.10.0 (v2026.4.16)** with post-release tracking for `main` · **21 parts, 13 installable skills, 5 opinionated configs, 4 reference architectures, one-command VPS bootstrap** · Battle-tested on a live production deployment
+>
+> Other languages: [中文](./README-zh.md) · [日本語](./README-ja.md)
 
 ### The End-to-End Hermes Guide — docs + runnable artifacts
 Every part you need to go from fresh install to a production Hermes deployment that talks on 16 platforms, orchestrates Claude Code / Codex / Gemini CLI, plugs into any MCP server, traces every call in Langfuse, and runs heavy work on disposable Modal/Daytona sandboxes — without burning $100/day on Opus tokens.
@@ -37,7 +40,7 @@ Prefer a 5-minute local-only setup? → **[docs/quickstart.md](./docs/quickstart
 
 | Folder | What's in it |
 |---|---|
-| [`skills/`](./skills) | **9 installable `SKILL.md`** files. `ln -s` into `~/.hermes/skills/` and they're live. |
+| [`skills/`](./skills) | **13 installable `SKILL.md`** files. `ln -s` into `~/.hermes/skills/` and they're live. |
 | [`templates/config/`](./templates/config) | **5 opinionated `config.yaml`** — minimum, telegram-bot, production, cost-optimized, security-hardened. |
 | [`templates/compose/`](./templates/compose) | Self-hosted Langfuse v3 stack (ClickHouse + MinIO + Redis). |
 | [`templates/caddy/`](./templates/caddy) | Caddyfile reference (reverse proxy + auto TLS + HSTS). |
@@ -46,6 +49,9 @@ Prefer a 5-minute local-only setup? → **[docs/quickstart.md](./docs/quickstart
 | [`scripts/vps-bootstrap.sh`](./scripts/vps-bootstrap.sh) | One-command fresh VPS → production Hermes. |
 | [`diagrams/`](./diagrams) | 6 Mermaid diagrams (architecture, MCP flow, delegation, sandbox sync, observability, security layers). |
 | [`benchmarks/`](./benchmarks) | Reproducible cost + latency table across 12 models × 5 tasks. |
+| [`docs/wizard/`](./docs/wizard) | **Interactive config wizard** — 8 questions → ready-to-drop `config.yaml`. Runs in your browser. |
+| [`docs/reference-architectures/`](./docs/reference-architectures) | **4 blueprints** — Homelab, Solo Dev, Small Agency, Road Warrior. Full parts list + cost + install. |
+| [`docs/outreach/`](./docs/outreach) | Launch tweet, HN post, upstream-PR body drafts (for people linking to this guide). |
 | [`docs/quickstart.md`](./docs/quickstart.md) | 5-minute zero-to-Telegram-bot. |
 | [`ECOSYSTEM.md`](./ECOSYSTEM.md) | Curated directory of MCP servers, coding agents, dashboard plugins. |
 | [`ROADMAP.md`](./ROADMAP.md) · [`CHANGELOG.md`](./CHANGELOG.md) · [`CONTRIBUTING.md`](./CONTRIBUTING.md) | The usual suspects. |

ROADMAP.md

@@ -4,20 +4,17 @@ What's landing next. PRs welcome.
 
 ## In progress
 
-- [ ] **Interactive config wizard** — a static page that asks 8 questions and emits a `config.yaml` + systemd unit. Hosted via GitHub Pages.
 - [ ] **GitHub Pages docs site** — Astro Starlight with full-text search across all parts + skills.
 - [ ] **Asciinema cast** — 60-second "zero to working Telegram bot" recording embedded in the README.
 - [ ] **Langfuse dashboard JSON** — importable ready-made dashboard for Hermes traces.
+- [ ] **Upstream PR** to `NousResearch/hermes-agent` README — add Community Guides section (draft in `docs/outreach/nous-upstream-pr-body.md`).
 
 ## Queued
 
 - [ ] **Skill templates** — `hermes skills new <name>` scaffolding generator
-- [ ] **Reference architectures** — homelab / single-user SaaS / small-team / agency, each with every file needed
-- [ ] **Integration tests** — GitHub Actions job that lints every SKILL.md frontmatter + validates YAML configs
-- [ ] **Cross-link checker** — CI check that fails if any `[...](./...)` link 404s
-- [ ] **Translations** — Chinese + Japanese (large Hermes user base in both communities per v0.9 release notes)
-- [ ] **"Hermes Weekly"** — markdown-first week-in-review section auto-generated from Hermes-agent merged PRs
+- [ ] **Cross-link checker** — CI check that fails if any `[...](./...)` link 404s (partial: markdown-link-check on modified files is live)
 - [ ] **Security CVE feed** — `.github/workflows/cve-watch.yml` that monitors OSV for relevant advisories
+- [ ] **Dashboard screenshots pass** — embed actual screens in parts 12 / 17 / 20
 
 ## Under consideration
 
@@ -27,6 +24,11 @@ What's landing next. PRs welcome.
 
 ## Done (recent)
 
+- ✅ 2026-04-17 — Interactive config wizard (`docs/wizard/`)
+- ✅ 2026-04-17 — 4 reference architectures (homelab / solo-dev / small-agency / road-warrior)
+- ✅ 2026-04-17 — CI (markdown-link-check + yamllint + skill frontmatter validator)
+- ✅ 2026-04-17 — Chinese + Japanese README entry pages
+- ✅ 2026-04-17 — Outreach drafts (tweet, HN, Reddit, upstream PR, blog post)
 - ✅ 2026-04-17 — Installable skill library + templates + bootstrap script
 - ✅ 2026-04-17 — MCP / coding-agent / security / observability / sandbox parts (17–21)
 - ✅ 2026-04-16 — v0.9 + v0.10 refresh (parts 12–16)

docs/outreach/README.md

@@ -0,0 +1,11 @@
+# Outreach Drafts
+
+Copy-ready materials for announcing / linking / promoting the guide. Keep these **out** of `README.md` — they're for posting, not for the repo front.
+
+- [`launch-tweet-thread.md`](./launch-tweet-thread.md) — X/Twitter launch thread, 8 tweets
+- [`hacker-news-post.md`](./hacker-news-post.md) — HN "Show HN" post + self-comment
+- [`reddit-localllama.md`](./reddit-localllama.md) — r/LocalLLaMA post
+- [`nous-upstream-pr-body.md`](./nous-upstream-pr-body.md) — body for a PR to `NousResearch/hermes-agent` README
+- [`blog-post-long.md`](./blog-post-long.md) — long-form blog post / Substack draft
+
+All drafts are **suggestions**. Fork the tone to yours before posting.