Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

docs: make the authoring cookbook Agent-first (#78)

smf-ha28f37251bb5
diff --git a/README.md b/README.md
index 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.md
index 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.md
index 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.md
new file mode 100644
index 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.md
new file mode 100644
index 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)。