@saluzi/saluzi-edu 0.4.7 → 0.4.8

package/dist/guide/guide-data.json

@@ -7187,7 +7187,7 @@
           "交互页面"
         ]
       },
-      "content": "\n## Artifacts 是什么\n\nArtifacts 是 agent 替你发布的**可分享 HTML 页面**：你在对话里让 agent 产出报告、看板或交互界面，它写好文件后用 `artifact` 工具上传，立刻得到一个稳定 URL，发给谁都能在浏览器打开。\n\n典型用途：\n\n- **团队交互界面** — PR 审查板、事故时间线、数据看板、发布清单（HTML 原样托管，`<script>` 可运行）\n- **进度与交付物** — 任务进度面板、调研报告、设计文档、数据可视化\n- **团队共享** — 接入 RCS 后，上传的页面自动出现在团队 Web 画廊，全员可见\n\n## 30 秒上手\n\n最短路径 — 直接在对话里说：\n\n```text\n把刚才的分析整理成一个 HTML 报告页，发布成 artifact 给我链接\n```\n\nagent 会自动完成：写文件 → 调用 `artifact` 工具上传 → 返回 `{ id, url, expiresAt }`。打开 `url` 即可查看。\n\n想更系统化地使用（复杂任务全程用一个「活文档」跟踪进度），让 agent 加载内置技能：\n\n```text\n/use-artifacts\n```\n\n它会教会 agent 何时该建 artifact、何时该更新、Markdown 与 HTML 怎么选。\n\n## 三种内容形态\n\n| 形态 | 适合场景 | 说明 |\n|------|---------|------|\n| **Markdown**（`.md`） | 文字为主的报告、设计文档、调研笔记 | 上传前自动转为带样式的 HTML（标题、GFM 表格、代码块高亮、引用、mermaid 图）。你只管写内容，排版交给工具 |\n| **HTML**（`.html`） | 定制布局、内嵌 SVG 图表、交互脚本 | 原样托管（包括 `<script>`），适合 PR 审查板、看板等可交互页面 |\n| **Archify 图表**（`.html`） | 架构图、流程图、时序图、数据流、状态机 | 内置 archify 渲染器把一份类型化 JSON 编译成**经过校验的**自包含交互页（明暗主题、缩放、路径探查），比手写 SVG 更专业可靠 |\n\n## 图表：/archify 模板\n\n需要画架构图 / CI-CD 流程 / API 时序 / 数据管道 / 状态机时，让 agent 运行：\n\n```text\n/archify 给这个仓库的请求路径画一张架构图，发布成 artifact\n```\n\nagent 的流水线：选定图类型 → 按内置 schema 编写 JSON 源（≤12 个主节点）→ 本地校验（不通过会按机器可读诊断自动修复）→ 编译出自包含 HTML → 用 `artifact` 工具上传进画廊。\n\n之后要改图（比如「加个 Redis 缓存层，链接别变」），agent 会改同一份 JSON 源、重新校验编译、再以原 `hash` 覆盖上传——**链接不变，图已更新**。产物还支持深链分享，如 `#route=网关~数据库` 可直接打开到某条调用路径。\n\n运行时查找顺序：`SALUZI_ARCHIFY_ROOT` 环境变量 → 项目 / 用户级已安装的 archify 技能 → CLI 内置副本（离线可用，无需安装任何东西）。\n\n两者都要求**绝对路径**，单文件不超过 **10MB**。\n\n## 更新而不换链接：hash 覆盖\n\n每次上传默认生成新 id（也就是新 URL）。要迭代同一个页面时，让 agent 把第一次返回的 `id` 作为 `hash` 传回：\n\n- URL **保持不变**，内容更新，版本号 +1，TTL 重新计时\n- 你可以把链接发出去后就不管了，agent 每完成一个阶段就原地更新\n\n这是「任务全程活文档」工作流的基础：任务开始先发布骨架，之后里程碑时用 `hash` 刷新，结束时就是最终交付物。\n\n## 会话内管理：/artifacts\n\n```text\n/artifacts\n```\n\n列出当前会话上传过的所有 artifact（最新的在最上面），含文件名、id、URL 和过期时间。键位：\n\n| 按键 | 作用 |\n|------|------|\n| `↑` / `↓` | 选择条目 |\n| `Enter` | 在浏览器打开选中项的 URL |\n| `c` | 复制 URL 到剪贴板 |\n| `Esc` / `q` | 退出 |\n\n## 团队画廊：RCS Web UI\n\n接入 RCS（见「Remote Control 与 ACP」章节）后，artifact 会上传到自托管服务器并归属当前会话，自动进入团队画廊：\n\n- **画廊页** `http://<rcs-host>:3000/code/artifacts` — 浏览所有你有权限查看的 artifact，展示大小、过期倒计时、所属会话\n- **从模板新建** — 画廊内可基于 5 个内置模板直接创建：空白页、PR 审查板、事故时间线、数据看板、发布清单（纯前端运行，无需构建）\n- **AI 生成 / AI 更新** — 新建与编辑对话框都可把需求派发给一个会话，由 agent 生成或迭代页面；已有 artifact 的「AI 更新」入口（卡片悬停操作行与详情页 ✨ 按钮）默认派发到归属会话（可改选），agent 以 `hash` 原位覆盖：链接不变、版本自增\n- **详情页实时刷新** — artifact 详情页订阅归属会话的 SSE 事件流，agent 上传新版本（或 CLI 覆盖）后 iframe 原位热更新，版本徽标闪烁提示\n- **会话详情页内嵌画廊** — 只显示该会话上传的 artifact，方便按会话回溯\n- **复制 / 删除** — 一键复制分享链接；创建者、会话/团队管理者或系统 admin 可删除\n- **可见性跟随会话** — 会话对谁可见，其 artifact 就对谁可见；画廊里新建的无会话 artifact 仅创建者与所属团队可见\n\n## 上传到哪：目标解析与配置\n\n`artifact` 工具按以下优先级选择上传目标（命中即停）：\n\n| 优先级 | 条件 | 上传地址 |\n|-------|------|---------|\n| 1 | 设置了 `SALUZI_ARTIFACTS_URL` | `{该地址}/v1/artifacts`（设 `SALUZI_ARTIFACTS_KIND=cloud` 则为 `{该地址}/upload`） |\n| 2 | 自托管 RCS bridge（`SALUZI_BRIDGE_BASE_URL` 默认 `http://localhost:3000`，同机 RCS 零配置命中） | `{SALUZI_BRIDGE_BASE_URL}/v1/artifacts`，归属当前会话，进入团队画廊 |\n| 3 | 都没有 | 默认云端 artifacts 服务（无需任何配置即可用，但不进 RCS 画廊） |\n\n相关环境变量：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `SALUZI_ARTIFACTS_URL` | 指定自托管上传地址（RCS 或云端兼容服务） |\n| `SALUZI_ARTIFACTS_TOKEN` | 上传认证 token（默认复用 bridge token） |\n| `SALUZI_ARTIFACTS_KIND` | 设为 `cloud` 表示目标是云端兼容服务（`/upload` 路径） |\n\nRCS 服务端还有一个开关：`RCS_ARTIFACTS_PUBLIC_ACCESS=false` 可把内容读取从「URL 即密钥」改为需要登录凭证（默认关闭公开访问开关，即默认任何人持链接可读）。\n\n## 限制与生命周期\n\n| 项目 | 值 |\n|------|-----|\n| 单文件上限 | 10MB |\n| 支持扩展名 | `.html` / `.htm` / `.md` / `.markdown` |\n| 保存时长（TTL） | 7 天（默认）或 30 天，上传时二选一 |\n| 过期行为 | 到期即删，链接失效（`hash` 重新上传可复活同一 id） |\n| 覆盖规则 | `hash` 仅接受字母/数字/`-`/`_`，最长 128 字符 |\n\n## 安全须知\n\n- **URL 即密钥**：id 是不可猜测的随机串，拿到链接的人即可查看 — 不要在 artifact 内容里放敏感信息（密钥、内网地址等）\n- 对外分享前确认内容可以公开；内网团队内容建议部署在受保护的 RCS 上并考虑设置 `RCS_ARTIFACTS_PUBLIC_ACCESS=false`\n- HTML 页面会原样执行脚本，仅上传可信内容\n\n## 故障排查\n\n| 问题 | 排查 |\n|------|------|\n| 上传报 `unauthorized` | 检查 `SALUZI_ARTIFACTS_TOKEN`；未设置时应复用 bridge token — 确认 `SALUZI_BRIDGE_OAUTH_TOKEN` 与 RCS 的 `RCS_API_KEYS` 匹配 |\n| 上传报 `payload_too_large` | 文件超过 10MB，精简内容或拆分页面 |\n| 报不支持扩展名 | 只接受 `.html` / `.htm` / `.md` / `.markdown`；把内容另存为这两种格式之一 |\n| 链接打不开（404） | artifact 可能已过期（默认 7 天）；让 agent 用原 `hash` 重新上传即可恢复同一 URL |\n| 团队画廊看不到 artifact | 确认 CLI 已连接 RCS bridge（`/rc` 状态正常）且未设置 `SALUZI_ARTIFACTS_URL` 指向别处；可见性跟随会话，确认你对会话有权限 |\n| 想让 artifact 不进云端 | 设置 `SALUZI_ARTIFACTS_URL` 指向自己的 RCS，或确保 bridge 已连接（优先级 2 自动生效） |\n"
+      "content": "\n## Artifacts 是什么\n\nArtifacts 是 agent 替你发布的**可分享 HTML 页面**：你在对话里让 agent 产出报告、看板或交互界面，它写好文件后用 `artifact` 工具上传，立刻得到一个稳定 URL，发给谁都能在浏览器打开。\n\n典型用途：\n\n- **团队交互界面** — PR 审查板、事故时间线、数据看板、发布清单（HTML 原样托管，`<script>` 可运行）\n- **进度与交付物** — 任务进度面板、调研报告、设计文档、数据可视化\n- **团队共享** — 接入 RCS 后，上传的页面自动出现在团队 Web 画廊，全员可见\n\n## 30 秒上手\n\n最短路径 — 直接在对话里说：\n\n```text\n把刚才的分析整理成一个 HTML 报告页，发布成 artifact 给我链接\n```\n\nagent 会自动完成：写文件 → 调用 `artifact` 工具上传 → 返回 `{ id, url, expiresAt }`。打开 `url` 即可查看。\n\n想更系统化地使用（复杂任务全程用一个「活文档」跟踪进度），让 agent 加载内置技能：\n\n```text\n/use-artifacts\n```\n\n它会教会 agent 何时该建 artifact、何时该更新、Markdown 与 HTML 怎么选。\n\n## 三种内容形态\n\n| 形态 | 适合场景 | 说明 |\n|------|---------|------|\n| **Markdown**（`.md`） | 文字为主的报告、设计文档、调研笔记 | 上传前自动转为带样式的 HTML（标题、GFM 表格、代码块高亮、引用、mermaid 图）。你只管写内容，排版交给工具 |\n| **HTML**（`.html`） | 定制布局、内嵌 SVG 图表、交互脚本 | 原样托管（包括 `<script>`），适合 PR 审查板、看板等可交互页面 |\n| **Archify 图表**（`.html`） | 架构图、流程图、时序图、数据流、状态机 | 内置 archify 渲染器把一份类型化 JSON 编译成**经过校验的**自包含交互页（明暗主题、缩放、路径探查），比手写 SVG 更专业可靠 |\n\n## 图表：/archify 模板\n\n需要画架构图 / CI-CD 流程 / API 时序 / 数据管道 / 状态机时，让 agent 运行：\n\n```text\n/archify 给这个仓库的请求路径画一张架构图，发布成 artifact\n```\n\nagent 的流水线：选定图类型 → 按内置 schema 编写 JSON 源（≤12 个主节点）→ 本地校验（不通过会按机器可读诊断自动修复）→ 编译出自包含 HTML → 用 `artifact` 工具上传进画廊。\n\n之后要改图（比如「加个 Redis 缓存层，链接别变」），agent 会改同一份 JSON 源、重新校验编译、再以原 `hash` 覆盖上传——**链接不变，图已更新**。产物还支持深链分享，如 `#route=网关~数据库` 可直接打开到某条调用路径。\n\n运行时查找顺序：`SALUZI_ARCHIFY_ROOT` 环境变量 → 项目级（`<项目>/.claude/skills/archify`）/ 用户级已安装的 archify 技能（Saluzi 的技能目录 `~/.saluzi-edu/skills/archify`，可用 `SALUZI_CONFIG_DIR` 改变；也兼容 Claude Code / Codex / opencode 的用户技能目录）→ CLI 内置副本（离线可用，无需安装任何东西）。如需手动安装上游技能，把 [archify.zip](https://github.com/tt-a1i/archify/raw/main/archify.zip) 解压到 `~/.saluzi-edu/skills/` 即可；不建议用 `npx skills add`——它会把技能播种到本机所有被检测到的 agent 目录里。\n\n两者都要求**绝对路径**，单文件不超过 **10MB**。\n\n## 更新而不换链接：hash 覆盖\n\n每次上传默认生成新 id（也就是新 URL）。要迭代同一个页面时，让 agent 把第一次返回的 `id` 作为 `hash` 传回：\n\n- URL **保持不变**，内容更新，版本号 +1，TTL 重新计时\n- 你可以把链接发出去后就不管了，agent 每完成一个阶段就原地更新\n\n这是「任务全程活文档」工作流的基础：任务开始先发布骨架，之后里程碑时用 `hash` 刷新，结束时就是最终交付物。\n\n## 会话内管理：/artifacts\n\n```text\n/artifacts\n```\n\n列出当前会话上传过的所有 artifact（最新的在最上面），含文件名、id、URL 和过期时间。键位：\n\n| 按键 | 作用 |\n|------|------|\n| `↑` / `↓` | 选择条目 |\n| `Enter` | 在浏览器打开选中项的 URL |\n| `c` | 复制 URL 到剪贴板 |\n| `Esc` / `q` | 退出 |\n\n## 团队画廊：RCS Web UI\n\n接入 RCS（见「Remote Control 与 ACP」章节）后，artifact 会上传到自托管服务器并归属当前会话，自动进入团队画廊：\n\n- **画廊页** `http://<rcs-host>:3000/code/artifacts` — 浏览所有你有权限查看的 artifact，展示大小、过期倒计时、所属会话\n- **从模板新建** — 画廊内可基于 5 个内置模板直接创建：空白页、PR 审查板、事故时间线、数据看板、发布清单（纯前端运行，无需构建）\n- **AI 生成 / AI 更新** — 新建与编辑对话框都可把需求派发给一个会话，由 agent 生成或迭代页面；已有 artifact 的「AI 更新」入口（卡片悬停操作行与详情页 ✨ 按钮）默认派发到归属会话（可改选），agent 以 `hash` 原位覆盖：链接不变、版本自增\n- **详情页实时刷新** — artifact 详情页订阅归属会话的 SSE 事件流，agent 上传新版本（或 CLI 覆盖）后 iframe 原位热更新，版本徽标闪烁提示\n- **会话详情页内嵌画廊** — 只显示该会话上传的 artifact，方便按会话回溯\n- **复制 / 删除** — 一键复制分享链接；创建者、会话/团队管理者或系统 admin 可删除\n- **可见性跟随会话** — 会话对谁可见，其 artifact 就对谁可见；画廊里新建的无会话 artifact 仅创建者与所属团队可见\n\n## 上传到哪：目标解析与配置\n\n`artifact` 工具按以下优先级选择上传目标（命中即停）：\n\n| 优先级 | 条件 | 上传地址 |\n|-------|------|---------|\n| 1 | 设置了 `SALUZI_ARTIFACTS_URL` | `{该地址}/v1/artifacts`（设 `SALUZI_ARTIFACTS_KIND=cloud` 则为 `{该地址}/upload`） |\n| 2 | 自托管 RCS bridge（`SALUZI_BRIDGE_BASE_URL` 默认 `http://localhost:3000`，同机 RCS 零配置命中） | `{SALUZI_BRIDGE_BASE_URL}/v1/artifacts`，归属当前会话，进入团队画廊 |\n| 3 | 都没有 | 默认云端 artifacts 服务（无需任何配置即可用，但不进 RCS 画廊） |\n\n相关环境变量：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `SALUZI_ARTIFACTS_URL` | 指定自托管上传地址（RCS 或云端兼容服务） |\n| `SALUZI_ARTIFACTS_TOKEN` | 上传认证 token（默认复用 bridge token） |\n| `SALUZI_ARTIFACTS_KIND` | 设为 `cloud` 表示目标是云端兼容服务（`/upload` 路径） |\n\nRCS 服务端还有一个开关：`RCS_ARTIFACTS_PUBLIC_ACCESS=false` 可把内容读取从「URL 即密钥」改为需要登录凭证（默认关闭公开访问开关，即默认任何人持链接可读）。\n\n## 限制与生命周期\n\n| 项目 | 值 |\n|------|-----|\n| 单文件上限 | 10MB |\n| 支持扩展名 | `.html` / `.htm` / `.md` / `.markdown` |\n| 保存时长（TTL） | 7 天（默认）或 30 天，上传时二选一 |\n| 过期行为 | 到期即删，链接失效（`hash` 重新上传可复活同一 id） |\n| 覆盖规则 | `hash` 仅接受字母/数字/`-`/`_`，最长 128 字符 |\n\n## 安全须知\n\n- **URL 即密钥**：id 是不可猜测的随机串，拿到链接的人即可查看 — 不要在 artifact 内容里放敏感信息（密钥、内网地址等）\n- 对外分享前确认内容可以公开；内网团队内容建议部署在受保护的 RCS 上并考虑设置 `RCS_ARTIFACTS_PUBLIC_ACCESS=false`\n- HTML 页面会原样执行脚本，仅上传可信内容\n\n## 故障排查\n\n| 问题 | 排查 |\n|------|------|\n| 上传报 `unauthorized` | 检查 `SALUZI_ARTIFACTS_TOKEN`；未设置时应复用 bridge token — 确认 `SALUZI_BRIDGE_OAUTH_TOKEN` 与 RCS 的 `RCS_API_KEYS` 匹配 |\n| 上传报 `payload_too_large` | 文件超过 10MB，精简内容或拆分页面 |\n| 报不支持扩展名 | 只接受 `.html` / `.htm` / `.md` / `.markdown`；把内容另存为这两种格式之一 |\n| 链接打不开（404） | artifact 可能已过期（默认 7 天）；让 agent 用原 `hash` 重新上传即可恢复同一 URL |\n| 团队画廊看不到 artifact | 确认 CLI 已连接 RCS bridge（`/rc` 状态正常）且未设置 `SALUZI_ARTIFACTS_URL` 指向别处；可见性跟随会话，确认你对会话有权限 |\n| 想让 artifact 不进云端 | 设置 `SALUZI_ARTIFACTS_URL` 指向自己的 RCS，或确保 bridge 已连接（优先级 2 自动生效） |\n"
     },
     "docs/guide/commit-workflow": {
       "frontmatter": {

package/dist/vendor/archify/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 tt-a1i (Archify)
+Copyright (c) 2025 Cocoon AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/vendor/archify/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: archify
+description: Create polished, validated architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as explorable standalone HTML with inline SVG, dark/light themes, optional trace motion, and PNG/JPEG/WebP/SVG/WebM export. Accept plain-language requirements or pasted Mermaid flowchart, sequenceDiagram, and stateDiagram input; inspect repository evidence when the diagram must reflect real code. Use when the user asks to visualize system architecture, infrastructure, cloud/security/network topology, technical workflows, API call sequences, request lifecycles, data pipelines, ETL/ELT, data lineage, state machines, or to convert/beautify Mermaid.
+license: MIT
+metadata:
+  version: "2.17"
+  author: tt-a1i
+  based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)
+---
+
+# Archify
+
+Create a self-contained, interactive HTML diagram from a small typed JSON specification. Static output is the default; enable motion only when the user asks for a demo or presentation.
+
+## Fast authoring path
+
+Use this bounded path for ordinary generation. Do not read the optional Viewer Runtime reference unless the user asks about those features.
+
+1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.
+2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and one matching JSON example in `examples/`. Read only those files. Fresh authorship means new stable IDs, domain wording, and layout; use the example for field shape, not facts. New workflow sources use `schema_version: 2` and its readable layout contract; keep `schema_version: 1` only when preserving an existing workflow's fixed geometry. When real product identity matters, query `node bin/archify.mjs brands "<name>" --json`; read `references/brand-marks.md` only for an unknown brand with a user-provided URL.
+3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, sparse labels, and at most 12 primary nodes. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; apply at most one diagnosed geometry control per repair.
+4. Validate after every candidate edit and immediately before handoff:
+
+   ```bash
+   node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
+   ```
+
+   A receipt with only 4 artifact checks is basic validation, never showcase acceptance. A showcase pass must report all 9 artifact checks with 0 composition errors and 0 warnings. If the candidate omits or misspells the exact `meta.quality_profile` field, fix it before geometry. For a workflow v2 geometry diagnosis, run `node bin/archify.mjs validate workflow <candidate.json> --layout-json` and use the stable compiler receipt; solver internals are not authoring controls. A passing final validation freezes the candidate: never edit it afterward.
+5. For a delivered HTML, `deliver` is the final acceptance command:
+
+   ```bash
+   node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
+   ```
+
+   A non-zero exit can never be described as success. A failed delivery preserves any previous output, so do not run `visual-check` on that path: it would inspect the stale last-good artifact, not the failed candidate. If validation fails, change only the diagnosed `subject`, verify `evidence`, choose from `supportedFixes`, and rerun. Continue focused correction while the objective error count reaches a new minimum. If two consecutive rounds do not improve that best count, stop and report the unresolved diagnostics truthfully.
+
+## Update awareness
+
+After the first candidate exists, run the packaged checker `scripts/check-update.mjs` once with Node and continue the requested workflow. If the command cannot run, continue without mentioning the check.
+
+- For `silent`, continue without mentioning the update check.
+- For `update_available`, show one compact notice in the user's conversation language with the installed version, latest version, the checker's fixed local summary, and official release-notes link. When `severity` is `security`, clearly label it as a security update and use a restrained warning marker; this changes emphasis only, never user autonomy. Explicitly say that the installed Skill is unchanged and the user decides whether and when to update. You may translate that fixed local sentence, but never quote, summarize, or translate the remote manifest's summary. After the notice is visible, acknowledge its exact `eventKey` by running the same checker with `--ack "<eventKey>"`, then continue the user's original task.
+
+The notice is information, not permission. Keep the installed version unchanged; this v0.1 workflow never downloads, installs, or executes an update, and silence is never consent.
+
+Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate. Inspect implementation only for an unsupported internal diagnostic or after two focused repairs fail.
+
+Workflow note: use schema v2 for new workflows; preserve schema v1 when an
+existing source needs fixed legacy geometry. Keep semantic edge labels and act
+on the compiler diagnostic. The canonical layout, pin, migration, and receipt
+contract is in [`renderers/workflow/README.md`](renderers/workflow/README.md#layout-contracts).
+
+Lifecycle note: phase columns `0..4` occupy the main rail; event/terminal column `N` in `0..2` aligns exactly beneath main column `N + 2`. A recoverable state uses `type: "failure"` plus a real transition back to the active state.
+
+## Type router
+
+| Type | Use for |
+|---|---|
+| `architecture` | Components, services, cloud/security boundaries, infrastructure |
+| `workflow` | Processes, approval gates, tool calls, runbooks, CI/CD |
+| `sequence` | API call chains, request lifecycles, async traces, returns |
+| `dataflow` | Pipelines, ETL/ELT, lineage, governance, consumers |
+| `lifecycle` | State/status transitions, retries, waiting and terminal states |
+
+When ambiguous, run `node bin/archify.mjs guide "<scenario>" --json`. Scenario proof examples are structural references, not facts to copy.
+
+## Mermaid input
+
+Read Mermaid for topology and meaning, then author fresh Archify JSON; do not mechanically render Mermaid styling.
+
+- `flowchart` / `graph` → `workflow`, or `architecture` for a component map.
+- `sequenceDiagram` → `sequence`; participants become semantic participants and arrows become messages.
+- `stateDiagram` → `lifecycle`; states and transitions retain meaning, not Mermaid style.
+
+## Authoring invariants
+
+- One obvious main path; side branches leave the nearest main-path node. Remove low-value edges before adding routing controls.
+- Omit `meta.visual_preset` by default so every diagram opens in `classic`, regardless of whether its resolved color mode is light or dark. Color mode and visual preset are independent: switching Light / Dark must preserve the current preset. Set `signal-flow`, `blueprint`, or `editorial` only when the user explicitly requests that visual style.
+- Omit `meta.subtitle` by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.
+- Treat the standalone desktop viewer as a first-screen artifact by default, not a shallow strip. Generate one responsive artifact for laptops and external displays—never device-specific HTML or alternate topology. The viewer may adapt only the outer reading width from the live viewport height; it must preserve the authored SVG/viewBox, proportions, semantic geometry, and normal document flow. On a wide or tall desktop, use enough authored vertical rhythm that the diagram panel and its necessary conclusion cards occupy the screen as a balanced whole; runtime scaling cannot repair an over-compressed Y layout or an undersized explicit `meta.viewBox`. Before handoff, open the real HTML at 1440×900, 1600×1000, and 1920×1080; additionally check 2048×1320 whenever the composition is intended for a large desktop display. Require `document.documentElement.scrollWidth <= window.innerWidth` and `scrollHeight <= window.innerHeight` at every checked size, while visually checking that the diagram remains comfortably readable and vertically balanced at the largest checked viewport. Repair overflow by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards. Never counterfeit a pass with `overflow: hidden`, clipped content, an internal diagram scroller, stretched SVG height, or smaller typography. Narrow/mobile layouts may scroll vertically when containment requires it.
+- Omit `meta.legend` for the truthful `auto` default. When needed, use only `mode: auto|all|hidden` and renderer-supported `entries.<kind>.label|visible`; labels never change semantics.
+- Choose one primary authored language from an explicit user choice; otherwise follow the request or conversation's dominant language. `meta.locale` controls only renderer-owned Viewer UI: use `"en"` or `"zh-CN"` for the corresponding supported primary language. For every other language, omit `meta.locale` and explicitly disclose that the fixed Viewer UI and `<html lang>` fall back to English. The renderer never translates authored content. See `references/authoring-contract.md` for details.
+- Preserve exact product names, code identifiers, commands, protocols, API paths, and environment names. They may remain English inside localized copy, but never justify leaving the surrounding explanatory prose in another language.
+- Brand identity is optional and explicit. Put a canonical built-in ID in `brand` when the node names that real product. If no preset matches and the user supplied the official HTTP(S) URL, first run `node bin/archify.mjs brands capture "<url>" --json`, then author the returned digest-pinned `brand` object. Render and validate never perform an unpinned capture. Otherwise omit `brand`. Never infer a brand from a vague role such as "database", and never let a badge replace the semantic `type`, label, or relationship facts.
+- For sequence diagrams, omit `meta.column_fit` for the stable `fixed` layout. Set it to `"spread"` when a wide viewBox would otherwise leave unused horizontal space or when meaningful participant labels do not fit the fixed boxes; do not shorten semantic labels before trying `spread`.
+- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.
+- Relationship labels are semantic data. When one collides, move the label, adjust the route or spacing, then shorten the wording while preserving meaning. Omit only wording that is already fully implied by both endpoints and contains no protocol, action, direction, synchronous/asynchronous behavior, or cross-boundary mechanism. Preserve every meaningful label; deleting it is not a geometry repair. If a relationship starts unlabeled because its endpoints fully imply it, explain why the wording is redundant; this is a semantic authoring choice, not a geometry repair.
+- Omit `meta.engineering_profile` by default. Region, cluster, and security boundary wording do not by themselves enable it. Enable `deployment-ownership` only when the user explicitly asks for a production deployment topology, ownership handoff, or fail-closed deployment review and the source facts are known. Once enabled, must not remove the engineering profile merely to pass validation; repair the facts or report the diagnostics truthfully.
+- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.
+- Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.
+- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps unobstructed facing automatic ports (`left`/`right` or `top`/`bottom`) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.
+- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.
+
+Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.
+
+## Delivery
+
+Use `validate` during repair and `deliver` once for final acceptance. Delivery freezes the exact specification bytes into a private same-directory snapshot, renders and checks that snapshot, atomically commits the HTML, and reports SHA-256 plus byte counts for both specification and artifact. This is deterministic artifact evidence; it does not exercise the Viewer in a browser.
+
+After delivery, collect bounded desktop evidence without modifying or rerendering the trusted HTML:
+
+```bash
+node bin/archify.mjs visual-check <output.html> --json
+```
+
+`visual-check` collects automated browser evidence from the exact delivered HTML without modifying or rerendering it. Its machine-readable measurements and screenshots do not approve perceptual polish. Follow `references/delivery-contract.md` for the canonical receipt fields, coverage, sidecars, exit behavior, and supplementary manual-record requirements.
+
+Keep the three claims separate: `deliver` proves deterministic artifact checks, `visual-check` proves bounded behavior in a real browser, and perceptual visual review requires an actual human or image-capable reviewer. Report browser evidence and perceptual review independently. An unconstrained glance can support only perceptual review; use the canonical delivery contract when recording supplementary manual browser work or handling an environmental failure.
+
+Add `--open` only when the user wants an immediate local preview. For an active desktop authoring loop, the optional command is:
+
+```bash
+node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase
+```
+
+Never start preview by default. Read `references/delivery-contract.md` when using preview, repository evidence, export receipts, visual review, or post-commit opening.
+
+## Optional viewer capabilities
+
+Generated HTML already contains theme switching, pan/zoom, search, focus, relationship tracing, semantic views, presentation, and truthful exports. These are reader capabilities, not extra authoring work. `meta.animation: "trace"` is opt-in; `meta.views` is optional and should contain at most five curated chapters.
+
+Read `references/viewer-runtime.md` only when the user explicitly asks for Share Cards, Route/Reach cards, motion, guided stories, deep links, presentation, search/focus, or another Viewer Runtime feature.
+
+## Setup and fallback
+
+No install is required inside the skill package. Verify with:
+
+```bash
+node bin/archify.mjs doctor
+node bin/archify.mjs demo <output-directory>
+```
+
+When shell access is unavailable, hand-place architecture SVG into `assets/template.html`, use CSS semantic classes rather than inline colors, and follow the visual review contract in `references/delivery-contract.md`.
+
+## Output
+
+Return the checked HTML path, diagram type, validation summary, specification/artifact receipt, browser-evidence status, and truthful visual-review status. Do not claim success for a non-zero command or claim visual inspection you did not perform.

package/dist/vendor/archify/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,69 @@
+# Third-party notices
+
+Archify includes optional vector data for third-party brand marks. These marks
+are provided only to identify technologies and services in user-authored
+diagrams. Their inclusion does not imply sponsorship, endorsement, partnership,
+or affiliation with Archify.
+
+The Archify MIT license applies to Archify's own code and content. It does not
+replace the copyright licenses, trademark policies, or brand guidelines that
+apply to third-party marks. Users are responsible for confirming that their
+particular use is permitted.
+
+## Simple Icons
+
+Most of the built-in vector paths and their metadata were generated from
+[Simple Icons 16.28.0](https://github.com/simple-icons/simple-icons/tree/16.28.0).
+Simple Icons makes its collection work available under
+[CC0 1.0 Universal](https://github.com/simple-icons/simple-icons/blob/16.28.0/LICENSE.md).
+
+As Simple Icons explains in its
+[disclaimer](https://github.com/simple-icons/simple-icons/blob/16.28.0/DISCLAIMER.md),
+CC0 for the collection does not mean that every underlying icon is CC0. License
+and brand-guideline metadata may be incomplete or change over time. The absence
+of an individual license entry is not a grant of permission.
+
+Archify embeds the selected icons as vector-path data and may render them in a
+user-selected color. The following individual licenses were recorded in the
+pinned Simple Icons 16.28.0 metadata:
+
+| Mark | Recorded source | Recorded license | Archify treatment |
+|---|---|---|---|
+| Angular | [Angular press kit](https://angular.dev/press-kit) | [`CC-BY-4.0`](https://creativecommons.org/licenses/by/4.0/) | Embedded as vector-path data; color may be changed by the authored diagram. |
+| Apache Airflow | [Apache logos](https://apache.org/logos) | [`Apache-2.0`](https://www.apache.org/licenses/LICENSE-2.0) | Embedded as vector-path data; Apache trademarks remain subject to the [ASF trademark policy](https://www.apache.org/foundation/marks/). |
+| Apache Kafka | [Apache logos](https://apache.org/logos) | [`Apache-2.0`](https://www.apache.org/licenses/LICENSE-2.0) | Embedded as vector-path data; Apache trademarks remain subject to the [ASF trademark policy](https://www.apache.org/foundation/marks/). |
+| .NET | [.NET brand repository](https://github.com/dotnet/brand/blob/c7d0f51b8ec59531332d05fb27a5b758a7a3d689/logo/dotnet-logo.svg) | [`CC0-1.0`](https://creativecommons.org/publicdomain/zero/1.0/) | Embedded as vector-path data; color may be changed by the authored diagram. |
+| JavaScript | [JS community logo](https://github.com/voodootikigod/logo.js/blob/1544bdeed6d618a6cfe4f0650d04ab8d9cfa76d9/js.svg) | [`MIT`](https://github.com/voodootikigod/logo.js/blob/1544bdeed6d618a6cfe4f0650d04ab8d9cfa76d9/LICENSE) | Embedded as vector-path data; color may be changed by the authored diagram. |
+| Jenkins | [Jenkins artwork source](https://get.jenkins.io/art/) | [`CC-BY-SA-3.0`](https://creativecommons.org/licenses/by-sa/3.0/) | Embedded as vector-path data; color may be changed by the authored diagram. Jenkins retains its trademark rights. |
+| Rust | [Rust project](https://www.rust-lang.org) | [`CC-BY-SA-4.0`](https://creativecommons.org/licenses/by-sa/4.0/) | Embedded as vector-path data; color may be changed by the authored diagram. See the [Rust media guide](https://www.rust-lang.org/policies/media-guide). |
+| Vue.js | [Vue logo source](https://github.com/vuejs/art/blob/a1c78b74569b70a25300925b4eacfefcc143b8f6/logo.svg) | [`CC-BY-NC-SA-4.0`](https://creativecommons.org/licenses/by-nc-sa/4.0/) | Embedded as vector-path data; color may be changed by the authored diagram. The non-commercial and share-alike conditions remain applicable; see the [Vue artwork terms](https://github.com/vuejs/art/blob/a1c78b74569b70a25300925b4eacfefcc143b8f6/README.md). |
+
+The source, guideline, and known license fields for every packaged mark are
+preserved in `renderers/shared/generated-brand-marks.mjs`.
+
+## OpenAI mark
+
+The OpenAI vector path is recorded from the
+[OpenAI brand guidelines](https://openai.com/brand/), not from Simple Icons.
+Use remains subject to those current guidelines and any applicable trademark
+rights. Its inclusion does not state or imply endorsement by OpenAI.
+
+## JetBrains Mono
+
+Delivered Archify viewer artifacts embed the JetBrains Mono variable font
+subsets served by Google Fonts. For characters covered by these subsets, font
+selection does not depend on a network request or a locally installed copy.
+Uncovered characters (including CJK) still use the system fallback stack;
+browser and operating-system rasterization can differ.
+JetBrains Mono is maintained at
+[github.com/JetBrains/JetBrainsMono](https://github.com/JetBrains/JetBrainsMono)
+and is distributed under the SIL Open Font License 1.1. The complete license
+text is preserved in `assets/JetBrainsMono-OFL.txt` in the packaged Skill and
+in the font CSS carried by standalone HTML and SVG exports.
+
+## No additional rights granted
+
+Brand names, logos, and trademarks remain the property of their respective
+owners. This notice records provenance and known terms; it does not grant rights
+that Archify does not hold, and it does not state that every packaged mark has
+been cleared for every commercial, promotional, or redistributive use.

package/dist/vendor/archify/assets/JetBrainsMono-OFL.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.