archify 是做什麼的？
從一個小型、型別化的 JSON 規格書建立自包含、可互動的 HTML 圖表。靜態輸出為預設值；僅在使用者要求示範或簡報時才啟用動畫。
快速創作路徑
使用此有限路徑處理一般圖表產生。除非使用者詢問相關功能，否則請勿閱讀選用的檢視器執行時期參考資料。
- 從問題中選擇
architecture、workflow、sequence、dataflow或lifecycle。 - 在
schemas/中讀取一個相符的綱要、schemas/common.schema.json，以及在examples/中讀取一個相符的 JSON 範例。僅讀取這些檔案。全新創作意味著新的穩定 ID、領域用詞與佈局；將範例用於欄位形狀，而非事實。 - 先產製成品：下一個工具動作必須寫入候選檔案。在檢查渲染器內部結構之前先寫入候選檔案。請勿以散文形式規劃確切座標。從一條清晰的主要路徑、簡短的側分支、稀疏的標籤開始，最多包含 12 個主要節點。將
meta.quality_profile設為"showcase"，除非使用者明確要求密集的standard地圖。從自動路由和標籤開始。在診斷要求之前，請勿新增via、channelX、channelY或labelAt；每次修復最多套用一個經診斷的幾何控制項。 - 在每次候選檔案編輯後以及交接前立即進行驗證：
node bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
一份僅包含 4 項成品檢查的收據是基本的驗證，絕非展示驗收。展示驗收必須報告所有 9 項成品檢查，且無任何組合錯誤或警告。如果候選檔案省略或拼錯 meta.quality_profile 欄位，請在處理幾何之前修正它。通過的最終驗證會凍結候選檔案：之後絕不再編輯它。
5. 對於已交付的 HTML，deliver 是最終的驗收指令：
node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
非零的退出碼絕不能描述為成功。如果驗證失敗，僅更改診斷出的 subject，驗證 evidence，從 supportedFixes 中選擇，然後重新執行。持續進行聚焦修正，直到客觀錯誤計數達到新的最小值。如果連續兩輪未能改善該最佳計數，則停止並如實報告未解決的診斷結果。
在建立第一個候選檔案之前，請勿閱讀 renderers/shared/geometry.mjs、渲染器原始碼、驗證器原始碼、測試或基準測試。僅在處理不支援的內部診斷時，或在兩次聚焦修復失敗後，才檢查實作。
生命週期備註：階段欄 0..4 佔據主要軌道；事件/結果欄 0..2 在後續階段下方對齊。可復原的狀態使用 type: "failure" 加上一個回到活動狀態的真實轉換。
類型路由器
| 類型 | 用途 |
|---|---|
architecture | 元件、服務、雲端/安全邊界、基礎設施 |
workflow | 流程、核准關卡、工具呼叫、操作手冊、CI/CD |
sequence | API 呼叫鏈、請求生命週期、非同步追蹤、回傳 |
dataflow | 管線、ETL/ELT、血緣、治理、消費者 |
lifecycle | 狀態/狀態轉換、重試、等待與終端狀態 |
當有歧義時，執行 node bin/archify.mjs guide "<scenario>" --json。情境證明範例是結構性參考，而非要抄襲的事實。
Mermaid 輸入
讀取 Mermaid 以獲取拓撲與意義，然後創作全新的 Archify JSON；請勿機械式地渲染 Mermaid 樣式。
flowchart/graph→workflow，或architecture用於元件圖。sequenceDiagram→sequence；參與者成為語意參與者，箭頭成為訊息。stateDiagram→lifecycle；狀態與轉換保留其意義，而非 Mermaid 樣式。
創作不變量
- 一條明顯的主要路徑；側分支從最近的主要路徑節點離開。在新增路由控制項之前，先移除低價值的邊。
- 對於真實的
auto預設值，省略meta.legend。需要時，僅使用mode: auto|all|hidden以及渲染器支援的entries.<kind>.label|visible；標籤絕不改變語意。 - 元件類型為
frontend、backend、database、cloud、security、messagebus和external；變體為default、emphasis、security和dashed。 - 間距指清晰間隙，而非中心距離。對於關係標籤，清晰間隙必須超過其測量的遮罩寬度；否則請省略該標籤或刻意移動它。
- 自動路由擁有其端點側。側邊是一種方向契約：第一段和最後一段必須垂直於該側進出。
- 自動埠分散是 architecture、workflow、data-flow 和 lifecycle 的預設渲染器行為。它會跳過單一關係和明確的
via、channelX、channelY、labelAt或非auto路由。接近的平行埠使用外部橋接，因此自動路由無法建立小於 8px 的線段或小於 16px 的內部轉彎。 - 絕不接受一條邊穿過不相關的不透明節點、模糊的共享通道，或一個關係標籤遮蓋另一條路由。
僅在需要欄位列舉、間距數學、幾何修復規則、儲存庫證據或特定模式放置時，才閱讀 references/authoring-contract.md。
交付
在修復期間使用 validate，並在最終驗收時僅使用一次 deliver。交付會將確切的規格位元組凍結到私有的同目錄快照中，渲染並檢查該快照，原子性地提交 HTML，並報告規格與成品的 SHA-256 及位元組計數。
僅在使用者想要即時本地預覽時新增 --open。對於活躍的桌面創作迴圈，可選指令為：
node bin/archify.mjs preview <type> <input>.json <output>.html --quality showcase
預設情況下絕不啟動預覽。當使用預覽、儲存庫證據、匯出收據、視覺審查或提交後開啟時，請閱讀 references/delivery-contract.md。
選用檢視器功能
產生的 HTML 已包含主題切換、平移/縮放、搜尋、聚焦、關係追蹤、語意檢視、簡報以及如實的匯出。這些是讀者功能，而非額外的創作工作。meta.animation: "trace" 是選擇加入的；meta.views 是可選的，且應最多包含五個策劃章節。
僅在使用者明確要求分享卡、路由/到達卡、動畫、引導故事、深層連結、簡報、搜尋/聚焦或其他檢視器執行時期功能時，才閱讀 references/viewer-runtime.md。
設定與備用方案
在技能套件內部無需安裝。使用以下指令驗證：
node bin/archify.mjs doctor
node bin/archify.mjs demo <output-directory>
當無法使用 Shell 存取時，將架構 SVG 手動放入 assets/template.html，使用 CSS 語意類別而非內嵌顏色，並遵循 references/delivery-contract.md 中的視覺審查合約。
輸出
回傳已檢查的 HTML 路徑、圖表類型、驗證摘要、規格/成品收據，以及如實的視覺審查狀態。對於非零指令請勿宣稱成功，也不要宣稱你未執行的視覺檢查。