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
docs: make the authoring cookbook Agent-first (#78)
smf-ha28f37251bb5
diff --git a/README.md b/README.mdindex 87318652..4674c960 100644--- a/README.md+++ b/README.md@@ -269,9 +269,7 @@ The complete generation and viewer contract lives in [`archify/SKILL.md`](archif## Reference and scope-- [Schema reference](archify/schemas/README.md)-- [Skill and renderer contract](archify/SKILL.md)-- [Examples](archify/examples/)+- [Schema reference](archify/schemas/README.md) · [Skill](archify/SKILL.md) · [Examples](archify/examples/) · [Agent cookbook](docs/authoring-cookbook.md)- [Changelog](CHANGELOG.md)- [Roadmap](ROADMAP.md)- [Generated Proof Lab](https://tt-a1i.github.io/archify/gallery.html)diff --git a/README_EN.md b/README_EN.mdindex 87318652..4674c960 100644--- a/README_EN.md+++ b/README_EN.md@@ -269,9 +269,7 @@ The complete generation and viewer contract lives in [`archify/SKILL.md`](archif## Reference and scope-- [Schema reference](archify/schemas/README.md)-- [Skill and renderer contract](archify/SKILL.md)-- [Examples](archify/examples/)+- [Schema reference](archify/schemas/README.md) · [Skill](archify/SKILL.md) · [Examples](archify/examples/) · [Agent cookbook](docs/authoring-cookbook.md)- [Changelog](CHANGELOG.md)- [Roadmap](ROADMAP.md)- [Generated Proof Lab](https://tt-a1i.github.io/archify/gallery.html)diff --git a/README_ZH.md b/README_ZH.mdindex 0d244f5a..2d2a14e5 100644--- a/README_ZH.md+++ b/README_ZH.md@@ -271,6 +271,7 @@ Claude.ai 中的上传入口:- [Schema 说明](archify/schemas/README.md)- [Skill 与 Renderer 契约](archify/SKILL.md)- [示例](archify/examples/)+- [Agent 编图手册](docs/authoring-cookbook.zh-CN.md) · [English](docs/authoring-cookbook.md)- [版本历史](CHANGELOG.md)- [路线图](ROADMAP.md)- [自动生成的 Proof Lab](https://tt-a1i.github.io/archify/gallery.html)diff --git a/docs/authoring-cookbook.md b/docs/authoring-cookbook.mdnew file mode 100644index 00000000..71a0495b--- /dev/null+++ b/docs/authoring-cookbook.md@@ -0,0 +1,106 @@+# Authoring Cookbook++Archify is primarily an Agent-facing Skill. Normal users can ask a Skill-capable Agent to generate the diagram; they do not need to learn the schema or run `validate`, `inspect`, or `deliver` themselves.++The manual workflow below is a reference for integration, contribution, and troubleshooting. The commands assume that you are in the repository's `archify/` directory, or in the root of an installed Archify skill.++## 1. Check the installation++Archify requires Node.js 18 or later. Run the doctor command before authoring a diagram:++```bash+node bin/archify.mjs doctor+```++If you are installing from npm-compatible skill tooling, the global install is:++```bash+npx skills add tt-a1i/archify -g+```++## 2. Choose a diagram type++Use the type that matches the question you want the reader to answer:++| Type | Use it for | Start with |+| --- | --- | --- |+| `architecture` | Components, services, storage, and boundaries | `examples/web-app.architecture.json` |+| `workflow` | Ordered work, approvals, branches, and runbooks | `examples/agent-tool-call.workflow.json` |+| `sequence` | Calls, returns, cache misses, and timing | `examples/cache-miss-request.sequence.json` |+| `dataflow` | Data movement, transformations, and consumers | `examples/product-analytics.dataflow.json` |+| `lifecycle` | States, retries, waits, and terminal outcomes | `examples/agent-run.lifecycle.json` |++When the type is unclear, ask the built-in scenario guide:++```bash+node bin/archify.mjs guide "Show an API request with a Redis cache miss" --json+```++The guide recommends a type and returns a recipe. It does not create the diagram for you.++## 3. Author one bounded source file++Start with one clear story. Keep the first diagram to roughly 8–12 primary nodes, one main path, and only the branches that help explain the question. The checked-in examples are safer starting points than copying a large generated artifact.++Every source needs a `schema_version`, a `diagram_type`, a `meta.title`, and the structural arrays required by that renderer. Read the [schema reference](../archify/schemas/README.md) for the exact fields and allowed values.++For a repository-backed Architecture diagram, add revision-pinned repository metadata and source ranges to the JSON, then pass the local repository path to the command:++```bash+node bin/archify.mjs validate architecture path/to/diagram.json \+ --repo-root path/to/repository --quality showcase --json+```++Archify verifies the Git origin, commit, blobs, and requested lines. Do not add source evidence when the repository or revision cannot be verified.++## 4. Validate before rendering a handoff++Use `standard` while exploring and `showcase` for a polished artifact or checked-in proof:++```bash+node bin/archify.mjs validate architecture examples/web-app.architecture.json \+ --quality showcase --json+```++On success, the JSON receipt contains the artifact checks and composition summary. On failure, it contains a `stage` and `diagnostics[]`; repair the named subject and use the listed `supportedFixes` before trying another change. A non-zero exit code is never a successful validation.++For Architecture layout inspection, use the renderer's machine-readable layout output:++```bash+node bin/archify.mjs inspect architecture path/to/diagram.json+```++`inspect` is currently Architecture-only and is useful when a geometry diagnostic names a route or placement problem.++## 5. Deliver the trusted artifact++`render` is useful for a quick local output. Use `deliver` when the file is a handoff, release artifact, or CI output:++```bash+node bin/archify.mjs deliver architecture examples/web-app.architecture.json \+ web-app.html --quality showcase --json+```++`deliver` freezes the input bytes, renders a same-directory candidate, runs the final artifact checks, and replaces the target only after every gate passes. Its receipt includes specification and artifact SHA-256 hashes. Add `--open` only for an interactive local handoff:++```bash+node bin/archify.mjs deliver architecture examples/web-app.architecture.json \+ web-app.html --quality showcase --open --json+```++To compare two Architecture snapshots, use `compare`. It writes the HTML and a sidecar receipt beside it:++```bash+node bin/archify.mjs compare architecture base.json head.json \+ architecture-delta.html --quality showcase --json+```++## 6. Inspect the exact final file++The deterministic checks do not prove visual polish. Open the exact delivered HTML in a browser, or collect automated containment evidence when Chrome or Chromium is available:++```bash+node bin/archify.mjs visual-check web-app.html --json+```++Use the [delivery contract](../archify/references/delivery-contract.md) for the required visual-review status and handoff fields. The [Skill contract](../archify/SKILL.md) explains the authoring invariants and the bounded repair loop.diff --git a/docs/authoring-cookbook.zh-CN.md b/docs/authoring-cookbook.zh-CN.mdnew file mode 100644index 00000000..cdef4b32--- /dev/null+++ b/docs/authoring-cookbook.zh-CN.md@@ -0,0 +1,106 @@+# Archify 编图实践手册++Archify 首先是面向 Agent 的 Skill。普通用户只需向支持 Skill 的 Agent 描述想要的图;不必学习 Schema,也不必自己运行 `validate`、`inspect` 或 `deliver`。++下面的手工流程面向集成、贡献和排错。命令假设你位于仓库的 `archify/` 目录,或已经安装好的 Archify Skill 根目录。++## 1. 检查安装++Archify 要求 Node.js 18 或更高版本。开始编图前先运行 doctor:++```bash+node bin/archify.mjs doctor+```++如果通过兼容 npm 的 Skill 工具安装,可以执行:++```bash+npx skills add tt-a1i/archify -g+```++## 2. 选择图表类型++根据读者需要回答的问题选择类型:++| 类型 | 适合说明 | 可从这里开始 |+| --- | --- | --- |+| `architecture` | 组件、服务、存储和边界 | `examples/web-app.architecture.json` |+| `workflow` | 有序工作、审批、分支和 Runbook | `examples/agent-tool-call.workflow.json` |+| `sequence` | 调用、返回、缓存未命中和时序 | `examples/cache-miss-request.sequence.json` |+| `dataflow` | 数据移动、转换和消费者 | `examples/product-analytics.dataflow.json` |+| `lifecycle` | 状态、重试、等待和终态 | `examples/agent-run.lifecycle.json` |++不确定类型时,可以询问内置场景指南:++```bash+node bin/archify.mjs guide "展示带 Redis 缓存未命中的 API 请求" --json --lang zh+```++指南会推荐类型并返回配方,但不会替你创建图。++## 3. 编写边界清楚的源文件++从一个明确故事开始。第一张图建议只保留约 8–12 个主要节点、一条主路径,以及确实能帮助解释问题的分支。相比复制大型生成成品,直接参考仓库内示例更稳妥。++每个源文件都需要 `schema_version`、`diagram_type`、`meta.title`,以及对应 Renderer 要求的结构数组。精确字段和允许值请阅读 [Schema 说明](../archify/schemas/README.md)。++如果要生成基于仓库证据的 Architecture 图,需要在 JSON 中加入固定版本的仓库元数据和源码范围,再把本地仓库路径传给命令:++```bash+node bin/archify.mjs validate architecture path/to/diagram.json \+ --repo-root path/to/repository --quality showcase --json+```++Archify 会校验 Git 远端、commit、blob 和请求的代码行。无法验证仓库或版本时,不要添加源码证据。++## 4. 先校验,再交付++探索阶段可以使用 `standard`,正式成品或仓库内证明建议使用 `showcase`:++```bash+node bin/archify.mjs validate architecture examples/web-app.architecture.json \+ --quality showcase --json+```++成功时,JSON 回执包含成品检查和构图摘要。失败时,回执包含 `stage` 和 `diagnostics[]`;只修复被点名的对象,并优先使用 `supportedFixes` 中列出的修复方式。退出码非零时,绝不能描述为校验成功。++Architecture 图需要检查布局时,可以使用 Renderer 的机器可读布局输出:++```bash+node bin/archify.mjs inspect architecture path/to/diagram.json+```++`inspect` 当前只支持 Architecture,适合诊断信息指向线路或摆放问题时使用。++## 5. 交付可信成品++`render` 适合快速本地输出;当文件要交给别人、用于发布或作为 CI 产物时,请使用 `deliver`:++```bash+node bin/archify.mjs deliver architecture examples/web-app.architecture.json \+ web-app.html --quality showcase --json+```++`deliver` 会冻结输入字节,在目标文件同目录生成候选文件,运行最终成品检查,并且只在全部门禁通过后替换目标。回执包含源文件和成品的 SHA-256 哈希。只有需要立即本地打开时才加 `--open`:++```bash+node bin/archify.mjs deliver architecture examples/web-app.architecture.json \+ web-app.html --quality showcase --open --json+```++要比较两份 Architecture 快照,请使用 `compare`。它会在 HTML 旁边写入 sidecar 回执:++```bash+node bin/archify.mjs compare architecture base.json head.json \+ architecture-delta.html --quality showcase --json+```++## 6. 检查最终文件++确定性校验不能证明视觉效果。请在浏览器中打开刚刚交付的 HTML;如果环境有 Chrome 或 Chromium,也可以收集自动化的边界证据:++```bash+node bin/archify.mjs visual-check web-app.html --json+```++视觉复核状态和交付回执字段请参阅 [交付契约](../archify/references/delivery-contract.md)。编图不变量和有上限的修复循环请参阅 [Skill 契约](../archify/SKILL.md)。