Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
feat: add Skill-only Hermes Agent install path
Sayujaya1487993ef89953
diff --git a/.gitignore b/.gitignoreindex 499aeb54..2be3b0cb 100644--- a/.gitignore+++ b/.gitignore@@ -4,3 +4,5 @@ node_modules/.claude/.lore//.impeccable/+__pycache__/+*.py[cod]diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 30329104..4ef26aa3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,9 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo> Development identity: `v2.17.0-dev.1`. Not a stable release.+### Added+- **Hermes Agent community opt-in.** `integrations/hermes-agent` is a Skill-only directory plugin: it registers the existing Node Archify `SKILL.md` for Hermes. The documented install is `hermes skills install skills-sh/tt-a1i/archify/archify -y` (published GitHub Skill). A checkout symlink remains the local-dev path. Hermes still runs `node bin/archify.mjs`. This is not an official Nous product and is not an agent-switcher target.+### Fixed- **License provenance in distributions.** Source and packaged Skill distributions retain Cocoon AI's exact MIT copyright notice, package staging and smoke tests fail closed when the notice or LICENSE is missing or altered, and the deterministic ZIP carries the same LICENSE bytes as the repository.- **Third-party mark notices in distributions.** Source and packaged Skill distributions now identify the pinned Simple Icons collection, disclose all individual icon licenses recorded by that version, preserve source and brand-guideline links, and state that Archify's MIT license does not replace third-party copyright or trademark terms. Package staging and smoke tests fail closed when the notice is missing or altered.diff --git a/README.md b/README.mdindex 5983178b..ba05a970 100644--- a/README.md+++ b/README.md@@ -262,6 +262,7 @@ The complete generation and viewer contract lives in [`archify/SKILL.md`](archif| **opencode** | `~/.config/opencode/skills/`, `.opencode/skills/`, or `.agents/skills/` | Full renderer + validation workflow || **Claude.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox || **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture fallback |+| **Hermes Agent** | Opt-in: `hermes skills install skills-sh/tt-a1i/archify/archify -y` | Community Skill-only; Node `>=18`; not official Nous. [Details](integrations/hermes-agent/README.md). || **DeepSeek Harness** | Opt-in: `dsh plugin --profile web add @tt-a1i/[email protected]`. Invoke: `Use the archify skill to map this repository's runtime architecture.` Remove: `dsh plugin --profile web remove @tt-a1i/archify-dsh`. | Community integration for developer-preview `@deepseek-ai/[email protected]`; Node `^22.19.0 \|\| >=24.0.0`; not an official DeepSeek product. No telemetry. Shell files need exact workspace paths, not Web Produced Files. [Details](integrations/deepseek-harness/README.md). |## Reference and scopediff --git a/README_EN.md b/README_EN.mdindex 5983178b..ba05a970 100644--- a/README_EN.md+++ b/README_EN.md@@ -262,6 +262,7 @@ The complete generation and viewer contract lives in [`archify/SKILL.md`](archif| **opencode** | `~/.config/opencode/skills/`, `.opencode/skills/`, or `.agents/skills/` | Full renderer + validation workflow || **Claude.ai** | Upload `archify.zip` under Settings → Capabilities → Skills | Depends on Node.js access in the sandbox || **Project Knowledge** | Upload `archify.zip` to the project | Prompt-driven architecture fallback |+| **Hermes Agent** | Opt-in: `hermes skills install skills-sh/tt-a1i/archify/archify -y` | Community Skill-only; Node `>=18`; not official Nous. [Details](integrations/hermes-agent/README.md). || **DeepSeek Harness** | Opt-in: `dsh plugin --profile web add @tt-a1i/[email protected]`. Invoke: `Use the archify skill to map this repository's runtime architecture.` Remove: `dsh plugin --profile web remove @tt-a1i/archify-dsh`. | Community integration for developer-preview `@deepseek-ai/[email protected]`; Node `^22.19.0 \|\| >=24.0.0`; not an official DeepSeek product. No telemetry. Shell files need exact workspace paths, not Web Produced Files. [Details](integrations/deepseek-harness/README.md). |## Reference and scopediff --git a/README_ZH.md b/README_ZH.mdindex cb5a5d26..67dd5eaa 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -106,7 +106,7 @@ npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copynpx skills use tt-a1i/archify@archify --agent codex```-DeepSeek Harness(社区集成、显式启用):运行 `dsh plugin --profile web add @tt-a1i/[email protected]`;参见[兼容范围、限制与安全说明](integrations/deepseek-harness/README.md)。[Agent 切换器](https://tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture)只为 `cursor`、`codex`、`claude-code` 和 `opencode` 生成命令。Raven 仅支持 ZIP 手动安装:将 [`archify.zip`](archify.zip) 解压到 `~/.raven/workspace/skills`,解压后会得到 `~/.raven/workspace/skills/archify`;Raven 不属于切换器目标。+DeepSeek Harness(社区集成、显式启用):运行 `dsh plugin --profile web add @tt-a1i/[email protected]`;参见[兼容范围、限制与安全说明](integrations/deepseek-harness/README.md)。Hermes:`hermes skills install skills-sh/tt-a1i/archify/archify -y`;参见[说明](integrations/hermes-agent/README.md)。[Agent 切换器](https://tt-a1i.github.io/archify/start.html?agent=cursor&type=architecture)只为 `cursor`、`codex`、`claude-code` 和 `opencode` 生成命令。Raven 仅支持 ZIP 手动安装:将 [`archify.zip`](archify.zip) 解压到 `~/.raven/workspace/skills`,解压后会得到 `~/.raven/workspace/skills/archify`;Raven 不属于切换器目标。安装后的 Skill 包含一个低频、失败静默的发布检查,它最多只显示可选更新提醒,绝不会自行下载或安装更新。一次成功检查后,下次网络请求通常约在 72 小时(±20%)后发出;检查失败后,活跃使用可能在首次 6 小时、后续 24 小时退避到期时重试。请求只访问 `https://tt-a1i.github.io/archify/skill-updates/archify/stable.json`。服务端会自然获得 IP、请求时间和常规 HTTP 元数据;检查器不会发送本地版本、Agent、项目数据、用户输入、账户/设备标识,也不会保存或回传 ETag。是否更新以及何时更新始终由你决定。如需完全关闭检查(包括网络请求和提醒状态写入),请在 Agent 环境中设置 `ARCHIFY_UPDATE_CHECK_DISABLED=1`。@@ -258,6 +258,7 @@ node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tm| **opencode** | `~/.config/opencode/skills/`、`.opencode/skills/` 或 `.agents/skills/` | 完整 Renderer + Validation 工作流 || **Claude.ai** | Settings → Capabilities → Skills 中上传 `archify.zip` | 取决于沙箱是否提供 Node.js || **Project Knowledge** | 把 `archify.zip` 上传到项目 | Prompt 驱动的 Architecture Fallback |+| **Hermes Agent** | 显式启用:`hermes skills install skills-sh/tt-a1i/archify/archify -y` | 社区 Skill-only;Node `>=18`;不是 Nous 官方产品。没有遥测。非切换器目标。[详情](integrations/hermes-agent/README.md)。 || **DeepSeek Harness** | 显式启用:`dsh plugin --profile web add @tt-a1i/[email protected]`;调用:`Use the archify skill to map this repository's runtime architecture.`;卸载:`dsh plugin --profile web remove @tt-a1i/archify-dsh`。 | 面向开发者预览版 `@deepseek-ai/[email protected]` 的社区集成;Node `^22.19.0 \|\| >=24.0.0`;不是 DeepSeek 官方产品。没有遥测;shell 文件不会自动进入 Web Produced Files,请返回精确工作区路径。[详情](integrations/deepseek-harness/README.md)。 |Claude.ai 中的上传入口:diff --git a/archify/test/readme-showcase.test.mjs b/archify/test/readme-showcase.test.mjsindex cff3055f..75e5a66e 100644--- a/archify/test/readme-showcase.test.mjs+++ b/archify/test/readme-showcase.test.mjs@@ -156,6 +156,27 @@ test('README installation tables contain a complete DeepSeek Harness row', () =>}});+test('README installation tables include Hermes Agent before DeepSeek Harness', () => {+ for (const filename of ['README.md', 'README_EN.md', 'README_ZH.md']) {+ const readme = fs.readFileSync(path.join(repoRoot, filename), 'utf8');+ const hermes = readme.split('\n').find((line) => line.startsWith('| **Hermes Agent** |'));+ const dsh = readme.split('\n').find((line) => line.startsWith('| **DeepSeek Harness** |'));+ assert.ok(hermes, `${filename}: Hermes Agent must be an installation table row`);+ assert.ok(dsh, `${filename}: DeepSeek Harness must remain an installation table row`);+ assert.equal(+ (hermes.match(/(?<!\\)\|/g) || []).length,+ 4,+ `${filename}: Hermes Agent must have exactly three table cells`,+ );+ assert.ok(hermes.includes('Node `>=18`'), `${filename}: Hermes Agent must name Node >=18`);+ assert.ok(+ hermes.includes('hermes skills install skills-sh/tt-a1i/archify/archify -y'),+ `${filename}: Hermes Agent must document the skills.sh install identifier`,+ );+ assert.ok(readme.indexOf(hermes) < readme.indexOf(dsh), `${filename}: Hermes Agent must precede DeepSeek Harness`);+ }+});+test('README demos use checked-in captures and live deep links below the existing hero', () => {const demos = [{@@ -227,7 +248,7 @@ test('README stays scannable without deleting the visual proof set', () => {const wordCount = english.trim().split(/\s+/).length;const intro = english.slice(0, english.indexOf('![License]'));const introBullets = intro.match(/^- \*\*/gm) || [];- assert.ok(wordCount <= 2085, `README.md is too verbose again (${wordCount} words)`);+ assert.ok(wordCount <= 2110, `README.md is too verbose again (${wordCount} words)`);assert.ok(introBullets.length <= 8, `README.md has too many top-level capability bullets (${introBullets.length})`);const chinese = fs.readFileSync(path.join(repoRoot, 'README_ZH.md'), 'utf8');diff --git a/integrations/hermes-agent/.gitignore b/integrations/hermes-agent/.gitignorenew file mode 100644index 00000000..d78cbf72--- /dev/null+++ b/integrations/hermes-agent/.gitignore@@ -0,0 +1,4 @@+# Optional packed Skill copy used only when this plugin is shipped outside the repo.+skills/+__pycache__/+*.py[cod]diff --git a/integrations/hermes-agent/README.md b/integrations/hermes-agent/README.mdnew file mode 100644index 00000000..68cd43da--- /dev/null+++ b/integrations/hermes-agent/README.md@@ -0,0 +1,96 @@+# Archify for Hermes Agent++Community [Hermes Agent](https://hermes-agent.nousresearch.com/) integration for [Archify](https://github.com/tt-a1i/archify). This is **not** an official Nous Research product and does not imply Nous endorsement.++This is a **Skill-only** plugin. It does not register native Python render tools, telemetry, MCP servers, credentials handling, or background services. Hermes still needs **Node.js 18+**. The compiler remains `node bin/archify.mjs`.++There is no Python port of the renderers. A Python assistant uses Archify the same way Cursor does: author typed JSON, then run the Node CLI. Hermes is not an agent-switcher target.++## Install (shows up in available skills)++This command installs the published Skill from [`tt-a1i/archify`](https://github.com/tt-a1i/archify) (`archify/SKILL.md` plus the Node renderer). Hermes already indexes that package as `skills-sh/tt-a1i/archify/archify`. After this repository's Hermes docs land on `main`, keep using the same identifier; `skills.sh` may lag a few hours behind GitHub.++```bash+hermes skills install skills-sh/tt-a1i/archify/archify -y+```++Requires Node.js 18+ on the machine (or in the Hermes Docker image). Restart Hermes, then ask:++```text+Use the archify skill to map this repository's runtime architecture.+Show 8–12 core components, one primary path, external dependencies, and trust boundaries.+Put supporting detail in cards instead of adding more edges.+After delivery, return the exact workspace paths of the specification JSON and the HTML artifact.+```++Run `node bin/archify.mjs` from the installed Skill directory (`~/.hermes/skills/archify` or `%USERPROFILE%\.hermes\skills\archify`), or pass absolute paths.++If `hermes skills inspect skills-sh/tt-a1i/archify/archify` cannot resolve the identifier, wait for the skills.sh index or use the checkout symlink below. Do not invent a different owner/repo path: forks are different packages.++### Local checkout (this branch)++Replace the source path with your checkout.++Linux / macOS:++```bash+ln -sfn /absolute/path/to/archify/archify ~/.hermes/skills/archify+```++Windows PowerShell:++```powershell+New-Item -ItemType SymbolicLink -Force -Path "$env:USERPROFILE\.hermes\skills\archify" -Target "C:\absolute\path\to\archify\archify"+```++### Docker++Hermes Docker mounts `~/.hermes` at `/opt/data`. Run the install on the **host** so files land in that volume, or bind-mount `/absolute/path/to/archify/archify` to `/opt/data/skills/archify`. A host symlink whose target is outside the volume is invisible in the container.++## Optional namespaced plugin++Plugin skills are opt-in (`skill_view("archify:archify")`) and are not listed in the system prompt index. Install the Skill first so `register()` can resolve `SKILL.md` from `~/.hermes/skills/archify`. A checkout of this repository also works: `integrations/hermes-agent` falls back to `archify/SKILL.md`.++Linux / macOS:++```bash+ln -sfn /absolute/path/to/archify/integrations/hermes-agent ~/.hermes/plugins/archify+hermes plugins enable archify+```++Windows PowerShell:++```powershell+New-Item -ItemType SymbolicLink -Force -Path "$env:USERPROFILE\.hermes\plugins\archify" -Target "C:\absolute\path\to\archify\integrations\hermes-agent"+hermes plugins enable archify+```++`register()` looks for `SKILL.md` in this order: an optional packed `skills/archify` copy, the in-repo `archify/` package, `ARCHIFY_SKILL_ROOT`, then `HERMES_HOME/skills/archify` (default `~/.hermes/skills/archify`).++## Uninstall++```bash+hermes skills uninstall archify+```++Linux / macOS leftover cleanup:++```bash+rm ~/.hermes/skills/archify+hermes plugins disable archify+rm ~/.hermes/plugins/archify+```++Windows PowerShell:++```powershell+Remove-Item "$env:USERPROFILE\.hermes\skills\archify"+hermes plugins disable archify+Remove-Item "$env:USERPROFILE\.hermes\plugins\archify"+```++## Scope++- Compatible with Hermes directory plugins (`plugin.yaml` + `register(ctx)`).+- Does not add Archify to the Cursor / Codex / Claude Code / OpenCode agent switcher.+- Does not claim merge safety, blast radius, or live-infrastructure verification.diff --git a/integrations/hermes-agent/__init__.py b/integrations/hermes-agent/__init__.pynew file mode 100644index 00000000..b4e02372--- /dev/null+++ b/integrations/hermes-agent/__init__.py@@ -0,0 +1,59 @@+"""Skill-only Hermes plugin for Archify.++Registers the packaged Archify SKILL.md. It does not add native render tools,+network, credentials, or a Python rewrite of the Node compiler. Hermes follows+the skill and runs `node bin/archify.mjs` through its ordinary terminal tool.+"""++from __future__ import annotations++import os+from pathlib import Path++_PLUGIN_DIR = Path(__file__).resolve().parent+_SKILL_DESCRIPTION = (+ "Create polished, validated architecture, workflow, sequence, data-flow, "+ "and lifecycle diagrams as standalone HTML. Use when the user asks to "+ "visualize system architecture, infrastructure, workflows, API sequences, "+ "data pipelines, or state machines."+)+++def _hermes_home() -> Path:+ configured = os.environ.get("HERMES_HOME", "").strip()+ if configured:+ return Path(configured).expanduser()+ return Path.home() / ".hermes"+++def skill_md_candidates() -> list[Path]:+ candidates = [_PLUGIN_DIR / "skills" / "archify" / "SKILL.md"]+ integrations_dir = _PLUGIN_DIR.parent+ if integrations_dir.name == "integrations":+ candidates.append(integrations_dir.parent / "archify" / "SKILL.md")+ skill_root = os.environ.get("ARCHIFY_SKILL_ROOT", "").strip()+ if skill_root:+ candidates.append(Path(skill_root).expanduser() / "SKILL.md")+ candidates.append(_hermes_home() / "skills" / "archify" / "SKILL.md")+ return candidates+++def resolve_skill_md() -> Path:+ seen: set[Path] = set()+ for candidate in skill_md_candidates():+ resolved = candidate+ if resolved in seen:+ continue+ seen.add(resolved)+ if resolved.is_file():+ return resolved+ searched = ", ".join(str(path) for path in seen)+ raise FileNotFoundError(+ "archify plugin: SKILL.md not found. Install the Skill with a symlink "+ "to ~/.hermes/skills/archify, keep this plugin inside the Archify "+ f"checkout, or set ARCHIFY_SKILL_ROOT. Looked in: {searched}."+ )+++def register(ctx) -> None:+ ctx.register_skill("archify", resolve_skill_md(), description=_SKILL_DESCRIPTION)diff --git a/integrations/hermes-agent/plugin.yaml b/integrations/hermes-agent/plugin.yamlnew file mode 100644index 00000000..23c0c4f3--- /dev/null+++ b/integrations/hermes-agent/plugin.yaml@@ -0,0 +1,9 @@+name: archify+version: 0.1.0+description: Skill-only Archify plugin. Hermes loads the existing Node diagram skill; render, validate, and deliver still run as node bin/archify.mjs. Not an official Nous Research product.+author: tt-a1i+kind: standalone+platforms:+ - linux+ - macos+ - windowsdiff --git a/integrations/hermes-agent/test/plugin-contract.test.mjs b/integrations/hermes-agent/test/plugin-contract.test.mjsnew file mode 100644index 00000000..c7512707--- /dev/null+++ b/integrations/hermes-agent/test/plugin-contract.test.mjs@@ -0,0 +1,95 @@+import { spawnSync } from 'node:child_process';+import assert from 'node:assert/strict';+import fs from 'node:fs';+import path from 'node:path';+import test from 'node:test';+import { fileURLToPath } from 'node:url';++const here = path.dirname(fileURLToPath(import.meta.url));+const integrationRoot = path.resolve(here, '..');+const repoRoot = path.resolve(integrationRoot, '..', '..');++function read(relativePath) {+ return fs.readFileSync(path.join(integrationRoot, relativePath), 'utf8');+}++test('Hermes adapter lives only under integrations/hermes-agent', () => {+ assert.equal(fs.existsSync(path.join(integrationRoot, 'plugin.yaml')), true);+ assert.equal(fs.existsSync(path.join(integrationRoot, '__init__.py')), true);+ assert.equal(fs.existsSync(path.join(repoRoot, 'archify', 'SKILL.md')), true);+ assert.equal(fs.existsSync(path.join(integrationRoot, 'skills')), false);+});++test('plugin is skill-only and does not declare native tools', () => {+ const manifest = read('plugin.yaml');+ assert.match(manifest, /^name: archify$/m);+ assert.match(manifest, /^kind: standalone$/m);+ assert.doesNotMatch(manifest, /provides_tools/);+ assert.doesNotMatch(manifest, /provides_hooks/);++ const init = read('__init__.py');+ assert.match(init, /register_skill\("archify"/);+ assert.doesNotMatch(init, /register_tool\(/);+ assert.match(init, /node bin\/archify\.mjs/);+ assert.match(init, /ARCHIFY_SKILL_ROOT/);+ assert.match(init, /HERMES_HOME/);+});++test('register() resolves the in-repo Skill without a packed copy', () => {+ const result = spawnSync('python3', ['-c', `+import importlib.util+from pathlib import Path+plugin = Path(${JSON.stringify(path.join(integrationRoot, '__init__.py'))})+spec = importlib.util.spec_from_file_location('archify_hermes_plugin', plugin)+mod = importlib.util.module_from_spec(spec)+spec.loader.exec_module(mod)+resolved = mod.resolve_skill_md()+print(resolved)+assert resolved.name == 'SKILL.md'+assert resolved.parent.name == 'archify'+`], { encoding: 'utf8' });+ assert.equal(result.status, 0, result.stderr || result.stdout);+ assert.equal(path.resolve(result.stdout.trim()), path.join(repoRoot, 'archify', 'SKILL.md'));+});++test('docs stay community opt-in, cover Windows, and refuse a Python rewrite', () => {+ const docs = read('README.md');+ assert.match(docs, /not\*\* an official Nous Research/i);+ assert.match(docs, /Skill-only/);+ assert.match(docs, /Node\.js 18\+/);+ assert.match(docs, /no Python port/i);+ assert.match(docs, /hermes skills install skills-sh\/tt-a1i\/archify\/archify -y/);+ assert.match(docs, /~\/\.hermes\/skills\/archify/);+ assert.match(docs, /skill_view\("archify:archify"\)/);+ assert.match(docs, /New-Item -ItemType SymbolicLink/);+ assert.match(docs, /USERPROFILE/);+ assert.match(docs, /not an agent-switcher target/i);+});++test('README install tables mention Hermes without adding a switcher agent', () => {+ const english = fs.readFileSync(path.join(repoRoot, 'README.md'), 'utf8');+ const chinese = fs.readFileSync(path.join(repoRoot, 'README_ZH.md'), 'utf8');+ const start = fs.readFileSync(path.join(repoRoot, 'docs', 'start.html'), 'utf8');+ assert.match(english, /\| \*\*Hermes Agent\*\* \|/);+ assert.match(chinese, /\| \*\*Hermes Agent\*\* \|/);+ assert.match(english, /integrations\/hermes-agent\/README\.md/);+ assert.match(english, /hermes skills install skills-sh\/tt-a1i\/archify\/archify -y/);+ const skill = fs.readFileSync(path.join(repoRoot, 'archify', 'SKILL.md'), 'utf8');+ assert.match(skill, /^name: archify$/m);+ assert.doesNotMatch(start, /data-agent="hermes"/);+});++test('Archify core does not import or branch on Hermes Agent', () => {+ const grep = spawnSync('git', [+ 'grep',+ '-n',+ '-E',+ 'hermes-agent|HERMES_HOME|ARCHIFY_SKILL_ROOT',+ '--',+ 'archify',+ 'scripts/build-zip.sh',+ 'scripts/package-smoke.mjs',+ ], { cwd: repoRoot, encoding: 'utf8' });+ assert.equal(grep.status, 1, grep.stderr || grep.stdout);+ assert.equal(grep.stdout.trim(), '');+});