Skip to content

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

docs(website): clarify agent execution requirements and setup answers

tt-a1i9f878df3f195
diff --git a/website/src/content/agent-diagrams.en.md b/website/src/content/agent-diagrams.en.md
index e1fbe1db..2c3fab68 100644
--- a/website/src/content/agent-diagrams.en.md
+++ b/website/src/content/agent-diagrams.en.md
@@ -20,11 +20,35 @@ That distinction matters: Archify is not an independent source-code discovery se
## Set up your agent
-Open the [agent-aware quick start](start.html). Select the agent you actually use and choose a project-scoped or global installation. Follow the command shown there rather than copying another agent's installation path.
+Open the [agent-aware quick start](start.html). Select the agent you actually use and choose a project-scoped or global installation. The commands below are the same global, copy-based installations offered by Start, not commands for a plain web chat.
-The [installation reference](https://github.com/tt-a1i/archify/blob/main/README.md#installation-options) explains supported surfaces and their constraints. The renderer workflow needs an environment with file access and Node.js; requirements can differ by integration. Being able to chat with an AI model alone does not establish that the environment can run the workflow.
+### What environment does Archify need?
-Installation instructions are not a guarantee that every agent/version combination has been tested. If setup fails, record the agent, its version, your operating system, and the exact error before changing the diagram itself.
+Use a coding-agent environment that can read and write files and execute commands with Node.js. “No repository required” means you can supply a natural-language description without existing source code; the agent still needs a workspace to write JSON and HTML and run the renderer and checks. Viewing the finished HTML only needs a browser.
+
+The [installation reference](https://github.com/tt-a1i/archify/blob/main/README.md#installation-options) distinguishes these surfaces. Claude Code and Codex CLI support the full renderer and validation workflow. Claude.ai depends on Node.js access in its sandbox; uploading a ZIP to Project Knowledge is a prompt-driven fallback, not the same execution environment. Other integrations have their own requirements.
+
+<span id="setup-claude-code" class="section-anchor" aria-hidden="true"></span>
+
+### Install Archify for Claude Code
+
+For a global copied installation, run this in the terminal of the environment where you use Claude Code:
+
+<pre><code>npx -y skills add tt-a1i/archify --skill archify --agent claude-code --global --copy --yes</code></pre>
+
+Claude Code uses `~/.claude/skills/` for global skills or `.claude/skills/` in the project. For a project-scoped installation instead, choose [Claude Code in Start](start.html?agent=claude-code#install) and use “This repository only” from the intended project directory.
+
+<span id="setup-codex" class="section-anchor" aria-hidden="true"></span>
+
+### Install Archify for Codex CLI
+
+For a global copied installation, run this in the terminal of the environment where you use Codex CLI:
+
+<pre><code>npx -y skills add tt-a1i/archify --skill archify --agent codex --global --copy --yes</code></pre>
+
+Codex CLI uses `~/.agents/skills/` for global skills or `.agents/skills/` in the project. For a project-scoped installation instead, choose [Codex in Start](start.html?agent=codex#install) and use “This repository only” from the intended project directory.
+
+After installation, use the description or repository prompt in Start. Installation instructions are not a guarantee that every agent/version combination has been tested. If setup fails, record the agent, its version, your operating system, and the exact error before changing the diagram itself.
<span id="description-workflow" class="section-anchor" aria-hidden="true"></span>
diff --git a/website/src/content/agent-diagrams.zh.md b/website/src/content/agent-diagrams.zh.md
index 10c4d275..1fab812f 100644
--- a/website/src/content/agent-diagrams.zh.md
+++ b/website/src/content/agent-diagrams.zh.md
@@ -20,11 +20,35 @@ Archify 根据源文件生成 HTML,并执行对应的渲染与校验。你可
## 先配置你实际使用的 Agent
-打开[快速开始](start.html),选择自己的 Agent,再按需要选择项目级或全局安装。使用页面给出的对应命令,不要套用其他 Agent 的安装目录。
+打开[快速开始](start.html),选择自己的 Agent,再按需要选择项目级或全局安装。下面展示的是 Start 中相同的全局复制安装命令,不是在普通网页聊天框里执行的命令。
-[安装说明](https://github.com/tt-a1i/archify/blob/main/README.md#installation-options)列出了不同使用入口及限制。完整渲染流程需要文件访问和 Node.js 等环境能力,具体要求因集成方式而异。能与模型聊天,不等于当前环境能执行完整工作流。
+### Archify 需要什么运行环境?
-安装说明也不表示所有 Agent 版本组合都已验证。如果失败,先记录 Agent 及版本、操作系统和完整错误,再判断问题出在配置还是图表本身。
+使用能够读写文件、通过 Node.js 执行命令的 Coding Agent 环境。“不需要代码库”是指可以只提供自然语言描述,不必已有源码;Agent 仍需工作目录来写入 JSON、HTML,并执行渲染和校验。查看生成的 HTML 则只需要浏览器。
+
+[安装说明](https://github.com/tt-a1i/archify/blob/main/README.md#installation-options)区分了这些入口:Claude Code 和 Codex CLI 支持完整渲染与校验流程;Claude.ai 取决于沙箱是否能使用 Node.js;向 Project Knowledge 上传 ZIP 是提示词驱动的回退方式,不等于具备相同执行环境。其他集成方式有各自的要求。
+
+<span id="setup-claude-code" class="section-anchor" aria-hidden="true"></span>
+
+### 为 Claude Code 安装 Archify
+
+如果选择全局复制安装,在运行 Claude Code 的环境终端中执行:
+
+<pre><code>npx -y skills add tt-a1i/archify --skill archify --agent claude-code --global --copy --yes</code></pre>
+
+Claude Code 的全局 Skill 目录是 `~/.claude/skills/`,项目目录是 `.claude/skills/`。如果只想在当前项目使用,打开 [Start 的 Claude Code 选项](start.html?agent=claude-code#install),在目标项目目录中使用“仅安装到当前仓库”的命令。
+
+<span id="setup-codex" class="section-anchor" aria-hidden="true"></span>
+
+### 为 Codex CLI 安装 Archify
+
+如果选择全局复制安装,在运行 Codex CLI 的环境终端中执行:
+
+<pre><code>npx -y skills add tt-a1i/archify --skill archify --agent codex --global --copy --yes</code></pre>
+
+Codex CLI 的全局 Skill 目录是 `~/.agents/skills/`,项目目录是 `.agents/skills/`。如果只想在当前项目使用,打开 [Start 的 Codex 选项](start.html?agent=codex#install),在目标项目目录中使用“仅安装到当前仓库”的命令。
+
+安装完成后,使用 Start 中的文字描述或代码库提示词。安装说明不表示所有 Agent 版本组合都已验证。如果失败,先记录 Agent 及版本、操作系统和完整错误,再判断问题出在配置还是图表本身。
<span id="description-workflow" class="section-anchor" aria-hidden="true"></span>
diff --git a/website/src/pages/start.astro b/website/src/pages/start.astro
index 90531a5f..073246c6 100644
--- a/website/src/pages/start.astro
+++ b/website/src/pages/start.astro
@@ -23,15 +23,15 @@ const { lang = 'en' } = Astro.props;
<h1><span data-en="Describe it." data-zh="直接说,">Describe it.</span><span class="title-gap" aria-hidden="true"> </span><em data-en="Archify maps it." data-zh="Archify 就能画。">Archify maps it.</em></h1>
</div>
<div>
- <p class="lead-copy" data-en="No repository is required. Describe a plan, a process, or a system in a normal agent chat and Archify turns it into a checked, interactive diagram. If code exists, the same skill can inspect it for evidence." data-zh="不需要绑定代码库。在任意 Agent 对话里用大白话描述一份计划、一个流程或一套系统,Archify 就会把它变成经过校验的交互图;如果有代码,也可以再让它读取仓库作为证据。">No repository is required. Describe a plan, a process, or a system in a normal agent chat and Archify turns it into a checked, interactive diagram. If code exists, the same skill can inspect it for evidence.</p>
- <div class="trust-line" data-en="Your description is enough to make the first diagram." data-zh="只有一段描述,也足够画出第一张图。">Your description is enough to make the first diagram.</div>
+ <p class="lead-copy" data-en="No existing repository is required. Describe a plan, a process, or a system to a coding agent with Archify installed, file access, and command execution with Node.js. If code exists, the same skill can inspect it for evidence." data-zh="不需要已有代码库。向已安装 Archify、能够读写文件并通过 Node.js 执行命令的 Coding Agent 描述计划、流程或系统;如果有代码,也可以让它检查仓库作为证据。">No existing repository is required. Describe a plan, a process, or a system to a coding agent with Archify installed, file access, and command execution with Node.js. If code exists, the same skill can inspect it for evidence.</p>
+ <div class="trust-line" data-en="Start from your description once the agent environment is ready." data-zh="配置好 Agent 环境后,就可以从一段描述开始。">Start from your description once the agent environment is ready.</div>
</div>
</header>
<section class="type-shell" aria-labelledby="type-label">
<p class="type-label"><span data-en="Choose how to start" data-zh="选择如何开始">Choose how to start</span><strong data-en="Repository optional" data-zh="代码库可选">Repository optional</strong></p>
<div class="input-paths" role="tablist" aria-label="Input source">
- <button class="input-path" type="button" role="tab" data-input="description"><strong data-en="Just describe it" data-zh="直接描述">直接描述</strong><span data-en="Start in any chat. No files or repository needed." data-zh="在任意对话里开始,不需要文件或代码库。">Start in any chat. No files or repository needed.</span></button>
+ <button class="input-path" type="button" role="tab" data-input="description"><strong data-en="Just describe it" data-zh="直接描述">直接描述</strong><span data-en="No existing source files or repository needed. Use your configured coding agent." data-zh="无需已有源文件或代码库,使用已配置好的 Coding Agent。">No existing source files or repository needed. Use your configured coding agent.</span></button>
<button class="input-path" type="button" role="tab" data-input="repository"><strong data-en="Use a repository" data-zh="从代码库开始">Use a repository</strong><span data-en="Let the agent inspect code when source evidence matters." data-zh="需要源码证据时,再让 Agent 检查代码。">Let the agent inspect code when source evidence matters.</span></button>
</div>
<p class="question mermaid-guide-link"><a href="agent-diagrams.html#mermaid-input" data-en="Already have Mermaid? Learn how to use it as agent input →" data-zh="已有 Mermaid?了解怎样把它交给 Agent →">Already have Mermaid? Learn how to use it as agent input →</a></p>
@@ -53,6 +53,8 @@ const { lang = 'en' } = Astro.props;
<h2 data-en="Keep the tool local." data-zh="让工具留在本地。">Keep the tool local.</h2>
<p class="panel-intro" data-en="Choose Cursor, Codex, Claude Code, OpenCode, or GitHub Copilot. The switcher gives each one the same checked Skill and zero-dependency renderers—no vendor-specific fork." data-zh="选择 Cursor、Codex、Claude Code、OpenCode 或 GitHub Copilot。切换器为每个 Agent 提供同一份经过检查的 Skill 与零依赖渲染器,不维护厂商专属分叉。">Choose Cursor, Codex, Claude Code, OpenCode, or GitHub Copilot. The switcher gives each one the same checked Skill and zero-dependency renderers—no vendor-specific fork.</p>
+ <p class="question setup-guide-link"><a href="agent-diagrams.html#setup" data-en="Check environment requirements and Claude Code / Codex CLI setup →" data-zh="查看环境要求与 Claude Code / Codex CLI 配置说明 →">Check environment requirements and Claude Code / Codex CLI setup →</a></p>
+
<div class="agent-picker">
<p class="agent-picker-head"><span data-en="Choose your coding agent" data-zh="选择你的编码 Agent">Choose your coding agent</span><strong id="agent-state">Codex · same Skill</strong></p>
<div class="agent-tabs" role="tablist" aria-label="Coding agent">
diff --git a/website/test/agent-diagrams-browser.test.mjs b/website/test/agent-diagrams-browser.test.mjs
index 95fd2393..d95a1112 100644
--- a/website/test/agent-diagrams-browser.test.mjs
+++ b/website/test/agent-diagrams-browser.test.mjs
@@ -119,6 +119,7 @@ test('real Chrome: agent guide stays readable and navigable in both languages, t
// silently cropped or squeezed into an unreadable full-page thumbnail.
for (const [region, startId, endId] of [
['opening', null, 'responsibilities'],
+ ['setup', 'setup', 'description-workflow'],
['description-workflow', 'description-workflow', 'mermaid-input'],
['mermaid-input', 'mermaid-input', 'cache-scenarios'],
['cache-example', 'cache-scenarios', 'repository-evidence'],
@@ -151,6 +152,19 @@ test('real Chrome: agent guide stays readable and navigable in both languages, t
assert.ok(reading.pageWidth <= width + 1, 'no horizontal page overflow');
assert.deepEqual(reading.failures, [], 'all article text remains visible and unclipped');
}
+ // Follow each static setup answer into the existing interactive installer.
+ for (const agent of ['claude-code', 'codex']) {
+ await loadedAction(() => evaluate(`document.querySelector('.article-body a[href*="agent=${agent}#install"]').click()`));
+ assert.equal(await evaluate('location.pathname'), new URL(urlFor('start', lang)).pathname);
+ assert.equal(await evaluate('location.hash'), '#install');
+ assert.equal(await evaluate(`document.querySelector('[data-agent="${agent}"]').getAttribute('aria-selected')`), 'true');
+ assert.equal(await evaluate('document.getElementById("install-command").textContent.trim()'), `npx -y skills add tt-a1i/archify --skill archify --agent ${agent} --global --copy --yes`);
+ assert.equal(await evaluate('document.getElementById("project-command").textContent.trim()'), `npx -y skills add tt-a1i/archify --skill archify --agent ${agent} --copy --yes`);
+ await loadedAction(() => evaluate(`document.querySelector('.setup-guide-link a').click()`));
+ assert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', lang)).pathname);
+ assert.equal(await evaluate('location.hash'), '#setup');
+ await assertSectionVisible();
+ }
// Exercise real authored links, including section and locale continuity.
await evaluate(`document.querySelector('.article-toc a[href$="#cache-scenarios"]').click()`);
await settled();
@@ -189,23 +203,32 @@ test('real Chrome: agent guide stays readable and navigable in both languages, t
assert.equal(await evaluate(`document.querySelector('[data-input="description"]').getAttribute('aria-selected')`), 'true');
for (const theme of ['light', 'dark']) {
await evaluate(`if (document.documentElement.dataset.theme !== ${JSON.stringify(theme)}) document.querySelector('[data-theme-toggle]').click()`);
- await evaluate(`document.querySelector('.mermaid-guide-link').scrollIntoView({ block: 'center', behavior: 'instant' })`);
+ await evaluate(`scrollTo({ top: 0, behavior: 'instant' })`);
await settled();
- const help = await evaluate(`(() => {
- const link = document.querySelector('.mermaid-guide-link a'), style = getComputedStyle(link);
- const range = document.createRange(); range.selectNodeContents(link);
- const rects = [...range.getClientRects()];
- return { theme: document.documentElement.dataset.theme, pageWidth: document.documentElement.scrollWidth, visible: style.visibility === 'visible' && style.display !== 'none', rects: rects.map(({ left, right, top, bottom }) => ({ left, right, top, bottom })), navBottom: document.querySelector('.site-nav').getBoundingClientRect().bottom };
- })()`);
- assert.equal(help.theme, theme);
- assert.ok(help.visible && help.rects.length > 0, 'Start help is visible');
- assert.ok(help.pageWidth <= width + 1, 'Start has no horizontal page overflow');
- assert.ok(help.rects.every(box => box.left >= 0 && box.right <= width && box.top >= help.navBottom && box.bottom <= 1000), 'the complete Start help link is readable below navigation');
- const name = `agent-diagrams-${lang}-${width}-${theme}-start-help.png`;
- const image = await browser.cdp.send('Page.captureScreenshot', { format: 'png' }, session);
- fs.writeFileSync(path.join(output, name), Buffer.from(image.data, 'base64'));
- manifest.screenshots.push({ file: name, width, height: 1000, lang, theme, region: 'start-help', reading: help });
+ const leadName = `agent-diagrams-${lang}-${width}-${theme}-start-prerequisites.png`;
+ const leadImage = await browser.cdp.send('Page.captureScreenshot', { format: 'png' }, session);
+ fs.writeFileSync(path.join(output, leadName), Buffer.from(leadImage.data, 'base64'));
+ manifest.screenshots.push({ file: leadName, width, height: 1000, lang, theme, region: 'start-prerequisites' });
saveManifest();
+ for (const region of ['mermaid', 'setup']) {
+ await evaluate(`document.querySelector('.${region}-guide-link').scrollIntoView({ block: 'center', behavior: 'instant' })`);
+ await settled();
+ const help = await evaluate(`(() => {
+ const link = document.querySelector('.${region}-guide-link a'), style = getComputedStyle(link);
+ const range = document.createRange(); range.selectNodeContents(link);
+ const rects = [...range.getClientRects()];
+ return { theme: document.documentElement.dataset.theme, pageWidth: document.documentElement.scrollWidth, visible: style.visibility === 'visible' && style.display !== 'none', rects: rects.map(({ left, right, top, bottom }) => ({ left, right, top, bottom })), navBottom: document.querySelector('.site-nav').getBoundingClientRect().bottom };
+ })()`);
+ assert.equal(help.theme, theme);
+ assert.ok(help.visible && help.rects.length > 0, 'Start help is visible');
+ assert.ok(help.pageWidth <= width + 1, 'Start has no horizontal page overflow');
+ assert.ok(help.rects.every(box => box.left >= 0 && box.right <= width && box.top >= help.navBottom && box.bottom <= 1000), 'the complete Start help link is readable below navigation');
+ const name = `agent-diagrams-${lang}-${width}-${theme}-start-${region}-help.png`;
+ const image = await browser.cdp.send('Page.captureScreenshot', { format: 'png' }, session);
+ fs.writeFileSync(path.join(output, name), Buffer.from(image.data, 'base64'));
+ manifest.screenshots.push({ file: name, width, height: 1000, lang, theme, region: `start-${region}-help`, reading: help });
+ saveManifest();
+ }
}
await loadedAction(() => evaluate(`document.querySelector('.mermaid-guide-link a').click()`));
assert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', lang)).pathname);
@@ -223,7 +246,7 @@ test('real Chrome: agent guide stays readable and navigable in both languages, t
await navigate(urlFor('guide', lang));
await loadedAction(() => evaluate(`document.querySelector('.agent-guide-link a').click()`));
assert.equal(await evaluate('location.pathname'), new URL(urlFor('agent-diagrams', lang)).pathname);
- manifest.navigation.push({ width, lang, result: 'passed', tocPosition, localePosition, workflowPosition, workflowLocalePosition, mermaidPosition, mermaidLocalePosition, mermaidStartPosition, paths: ['toc', 'language with fragment', 'workflow section and locale', 'Mermaid section and locale', 'workflow description quick start', 'Start Mermaid help', 'existing leave artifact', 'article to start', 'start to article', 'guide to article'] });
+ manifest.navigation.push({ width, lang, result: 'passed', tocPosition, localePosition, workflowPosition, workflowLocalePosition, mermaidPosition, mermaidLocalePosition, mermaidStartPosition, paths: ['Claude Code setup to selected installer', 'Codex setup to selected installer', 'Start prerequisites back to setup', 'toc', 'language with fragment', 'workflow section and locale', 'Mermaid section and locale', 'workflow description quick start', 'Start Mermaid help', 'existing leave artifact', 'article to start', 'start to article', 'guide to article'] });
saveManifest();
}
} finally {
diff --git a/website/test/agent-diagrams.test.mjs b/website/test/agent-diagrams.test.mjs
index 74bd9105..ae784b0b 100644
--- a/website/test/agent-diagrams.test.mjs
+++ b/website/test/agent-diagrams.test.mjs
@@ -163,3 +163,35 @@ test('Mermaid guidance preserves the literal example, explains semantic reauthor
assert.deepEqual(entryNodes.filter(node => attr(node, 'data-input')).map(node => attr(node, 'data-input')), ['description', 'repository'], 'Mermaid help does not introduce a new input mode');
}
});
+
+
+test('setup answers are readable without scripts and distinguish prerequisites from optional source code', () => {
+ const origin = cloudflare ? 'https://archify.si/' : 'https://tt-a1i.github.io/archify/';
+ for (const lang of ['en', 'zh']) {
+ const prefix = lang === 'zh' ? 'zh/' : '';
+ const page = nodes(parse(fs.readFileSync(new URL(`${prefix}agent-diagrams.html`, output), 'utf8')));
+ const article = page.find(node => node.tagName === 'article');
+ const visible = text(article);
+ assert.match(visible, lang === 'en' ? /read and write files and execute commands with Node.js/ : /读写文件、通过 Node.js 执行命令/);
+ assert.match(visible, lang === 'en' ? /without existing source code/ : /不必已有源码/);
+ assert.match(visible, lang === 'en' ? /Claude.ai depends on Node.js access/ : /Claude.ai 取决于沙箱是否能使用 Node.js/);
+ assert.match(visible, lang === 'en' ? /prompt-driven fallback/ : /提示词驱动的回退方式/);
+ const base = new URL(attr(page.find(node => node.tagName === 'base'), 'href'), origin + `${prefix}agent-diagrams.html`);
+ for (const [agent, directory] of [['claude-code', '.claude'], ['codex', '.agents']]) {
+ assert.equal(page.filter(node => attr(node, 'id') === `setup-${agent}`).length, 1);
+ const command = `npx -y skills add tt-a1i/archify --skill archify --agent ${agent} --global --copy --yes`;
+ assert.ok(nodes(article).some(node => node.tagName === 'pre' && text(node).trim() === command), `${agent}: exact existing Start command is visible in SSR`);
+ for (const location of [`~/${directory}/skills/`, `${directory}/skills/`]) assert.ok(visible.includes(location));
+ const link = nodes(article).find(node => node.tagName === 'a' && attr(node, 'href')?.includes(`agent=${agent}#install`));
+ assert.equal(new URL(attr(link, 'href'), base).href, origin + `${prefix}start${cloudflare ? '' : '.html'}?agent=${agent}#install`);
+ }
+ const start = nodes(parse(fs.readFileSync(new URL(`${prefix}start.html`, output), 'utf8')));
+ const lead = start.find(node => attr(node, 'class') === 'lead');
+ assert.match(text(lead), /Node.js/);
+ assert.doesNotMatch(text(start.find(node => node.tagName === 'main')), /normal agent chat|Start in any chat|No files or repository needed|任意.*对话|不需要文件或代码库/);
+ const help = start.find(node => attr(node, 'class') === 'question setup-guide-link');
+ const helpLink = nodes(help).find(node => node.tagName === 'a');
+ assert.match(text(helpLink), lang === 'en' ? /environment requirements/ : /环境要求/);
+ assert.equal(new URL(attr(helpLink, 'href'), base).href, origin + `${prefix}agent-diagrams${cloudflare ? '' : '.html'}#setup`);
+ }
+});