@xgent-ai/skills 0.7.5 → 0.7.6

package/skills/phoenix-diagram/examples/minimal.tree.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": 1,
+  "diagram_type": "tree",
+  "meta": { "title": "Service ownership", "output": "minimal.tree.html", "input_contract": "phoenix-v1", "quality_profile": "showcase", "locale": "en" },
+  "nodes": [
+    { "id": "platform", "label": "Platform", "sublabel": "Owned capabilities" },
+    { "id": "payments", "label": "Payments", "parent": "platform" },
+    { "id": "card", "label": "Card payments", "parent": "payments" },
+    { "id": "wallet", "label": "Wallet payments", "parent": "payments" },
+    { "id": "operations", "label": "Operations", "parent": "platform", "collapsed": true },
+    { "id": "refunds", "label": "Refunds", "parent": "operations" }
+  ]
+}

package/skills/phoenix-diagram/examples/minimal.waterfall.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 1,
+  "diagram_type": "waterfall",
+  "meta": { "title": "Checkout request", "output": "minimal.waterfall.html", "input_contract": "phoenix-v1", "quality_profile": "showcase", "locale": "en", "evidence": "illustrative", "unit": "ms" },
+  "spans": [
+    { "id": "request", "name": "POST /checkout", "service": "checkout", "start": 0, "end": 420 },
+    { "id": "auth", "name": "Authenticate", "service": "identity", "parent": "request", "start": 0, "duration": 60 },
+    { "id": "stock", "name": "Reserve stock", "service": "inventory", "parent": "request", "start": 60, "duration": 180 },
+    { "id": "charge", "name": "Charge card", "service": "payments", "parent": "request", "start": 240, "duration": 150, "status": "error" },
+    { "id": "receipt", "name": "Send receipt", "parent": "request", "start": 390, "status": "incomplete" }
+  ]
+}

package/skills/phoenix-diagram/examples/minimal.workflow.json

@@ -0,0 +1,12 @@
+{
+  "schema_version": 2,
+  "diagram_type": "workflow",
+  "meta": { "title": "Request workflow", "output": "minimal.workflow.html", "input_contract": "phoenix-v1", "quality_profile": "showcase", "locale": "en" },
+  "lanes": [{ "id": "work", "label": "Work" }],
+  "nodes": [
+    { "id": "prepare", "lane": "work", "col": 0, "type": "backend", "label": "Prepare" },
+    { "id": "complete", "lane": "work", "col": 1, "type": "backend", "label": "Complete" }
+  ],
+  "edges": [{ "id": "continue", "from": "prepare", "to": "complete", "label": "Continue", "role": "main" }],
+  "mainPath": ["prepare", "complete"]
+}

package/skills/phoenix-diagram/references/architecture-compare.md

@@ -0,0 +1,111 @@
+# 架构比较
+
+仅在用户明确要求比较两份架构时使用。两份输入都必须是 `architecture`；其他图型继续使用各自的单图流程。比较只陈述输入中可追溯的变化，不推断运行影响、因果、风险或可合并性。
+
+## 输入与生成
+
+保留原 JSON。组件通过 `components[].id` 对应，连接通过作者明确写入的 `connections[].id` 对应，边界通过 `kind + label` 对应。边界键须唯一，两份输入至少共享一个组件 ID；两侧都写仓库时必须属于同一仓库。连接缺稳定 ID 时，普通单图仍可使用，比较会拒绝；由作者确认对应关系后再补 ID，不能按数组位置、标签相似度或端点猜同一关系。
+
+```sh
+"$PD" compare architecture base.json head.json comparison.html --json
+"$PD" compare architecture base.json head.json comparison.html \
+  --base-contract legacy-2.17 --head-contract phoenix-v1 \
+  --quality showcase --repo-root "<仓库根>" --brand-cache "<本地品牌缓存>" --json
+```
+
+合同选择按每侧明确标记处理，不重写源文件。`--quality` 与输入已有质量标记冲突时会失败；不要为换取比较通过而降低质量。仓库来源和品牌继续使用已固定的本地身份，普通比较不联网采集资源。
+
+默认比较回执为 `comparison.html.compare.json`；`--receipt PATH` 可指定同一物理父目录中的另一个文件。两份输入、HTML 和比较回执必须是四个不同的普通文件，拒绝符号链接或硬链接别名。
+
+比较回执包含双侧原始/语义摘要、编译配置、引擎、来源、品牌资源、比较 IR、HTML 身份和成对事务位置。`status: pass` 只表示本次比较和双成果发布已成功，`browserStatus: not-run`、`visualReview.status: required-pending`、`deliveryStatus: incomplete` 仍须如实保留。它不等于默认交付完成。
+
+## 阅读三个视图
+
+Before、Delta、After 分别展示原版、变化和新版。Delta 保留完整的新版事实，旧位置或已移除内容以幽灵层作对照；这些辅助图元不成为新版 Reader 的真实拓扑。点击变化列表定位相应对象，保留未变事实和每侧完整标签、来源及 Reader 控件。无变化时仍可读取原版和新版。
+
+字段变化分类为 semantic、evidence、geometry、topology、scope。来源变化与移动、改线等几何变化分开；数组重排、对象键顺序、来源条目顺序或 `meta.output` 改动不自行成为业务变化。仅在两侧来源已验证、仓库相同且提交已固定时为 `proofLevel: revision-pinned`，其他情况为 `authored`。
+
+## 自动检查与实际看图
+
+```sh
+"$PD" check comparison.html --strict-provenance --json
+"$PD" visual-check comparison.html --out-dir compare-evidence-01 --json
+```
+
+按 `visual-check` 返回的 `evidence.summaryReceipt` 和 `evidence.browserReceipt` 中的真实路径读取文件；两者都含 `identity: {sha256, bytes}`，不要猜文件名。比较的独立 summary 为 `kind: architecture-comparison-summary`，包含完整 `comparison` 绑定，以及真实的 `check`、`visual-check` 两门。它不复用普通 finalize 的四门 summary，也不改写原 HTML 或原比较回执。
+
+每个视图分别测量四个桌面窗口及窄屏，暗亮主题分别检查。实际看图使用浏览器回执中的 12 张当前截图：每个视图的 1440×900、2048×1320 各 light/dark。逐张打开，核对主图、标签、卡片、关系遮挡、层级和控件；Delta 还须核旧位置、删除标记和变化定位与输入相符。DOM 数值、截图存在或自动测试不能替代观察。
+
+自动两门均通过后，`automatedStatus` 才为 `pass`，视觉仍是 `required-pending`、交付仍为 `incomplete`。缺工具、浏览器失败、某视图缺测或尚未实际看图分别报告，不沿用普通单图或另一次比较的审核。
+
+## 创建完整审核草稿
+
+将以下 summary 路径换成 `visual-check` 回执中的真实值。Node.js 18+ 可运行，不需要源码或 Rust。示例只复制绑定，不能替代打开图片；空 reviewer、`observed: false` 和 `verdict: unavailable` 必须按实际观察填写。
+
+```sh
+node - "<比较summary真实路径>" "comparison-review-01.json" <<'NODE'
+const fs = require('node:fs');
+const assert = require('node:assert/strict');
+const [summaryPath, recordPath] = process.argv.slice(2);
+const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
+const names = ['check', 'visual-check'];
+if (summary.kind !== 'architecture-comparison-summary' || summary.automatedStatus !== 'pass'
+    || summary.stages.length !== 2 || !names.every((name, index) =>
+      summary.stages[index].name === name && summary.stages[index].status === 'pass')) {
+  throw new Error('Both current comparison automated gates must pass before review.');
+}
+const browserRef = summary.evidence.browserReceipt;
+const browser = JSON.parse(fs.readFileSync(browserRef.path, 'utf8'));
+assert.deepStrictEqual(browser.comparison, summary.comparison);
+if (browser.status !== 'pass' || browser.screenshots.length !== 12) {
+  throw new Error('Twelve current screenshots from all three views are required.');
+}
+const expected = new Set(['before', 'delta', 'after'].flatMap(view =>
+  ['1440x900', '2048x1320'].flatMap(size => ['light', 'dark'].map(theme => `${view}/${size}/${theme}`))));
+const actual = browser.screenshots.map(shot =>
+  `${shot.viewId}/${shot.viewport.width}x${shot.viewport.height}/${shot.theme}`);
+if (new Set(actual).size !== 12 || actual.some(key => !expected.has(key))) {
+  throw new Error('Comparison screenshot view, viewport or theme coverage differs.');
+}
+const record = {
+  schemaVersion: 1,
+  kind: 'architecture-comparison-review',
+  command: 'review-record',
+  comparison: summary.comparison,
+  browserReceipt: browserRef,
+  screenshotIdentities: browser.screenshots.map(shot => ({
+    viewId: shot.viewId,
+    file: { path: shot.path, identity: shot.identity },
+    viewport: shot.viewport,
+    theme: shot.theme,
+    observed: false,
+    observations: ''
+  })),
+  reviewer: '',
+  scope: ['diagram', 'labels', 'cards', 'relationship-occlusion', 'hierarchy', 'controls'],
+  verdict: 'unavailable',
+  findings: ['Image review has not been performed.']
+};
+fs.writeFileSync(recordPath, JSON.stringify(record, null, 2) + '\n', { flag: 'wx' });
+NODE
+```
+
+填写真实 reviewer；已打开的每张图写 `observed: true` 与非空 `observations`。没有缺陷才能用 `verdict: passed`、`findings: []`；有缺陷用 `failed` 并写具体 findings；无法看图用 `unavailable` 并写实际限制。所有记录都必须保留双输入完整绑定与 12 张原件身份，不加未知字段，不用单图记录替代。
+
+```sh
+"$PD" review-record comparison.html --record comparison-review-01.json --json
+```
+
+读取返回的 `evidence.summaryReceipt.path`。只有同一 `comparison` 的两门为 pass、`automatedStatus: pass`、`visualReview.status: passed`、`deliveryStatus: complete`，身份仍匹配当前输入、配置、资源、引擎、IR、HTML、比较回执和截图，才能报告完成。`failed` 或 `unavailable` 的观察结果保持 `incomplete`。
+
+相同已封存记录可幂等重试。若封存完成但 summary 更新失败，保留同一记录字节，解决摘要冲突或输出恢复后重试 `review-record`；不要再次 compare/visual-check 取得另一个身份。不同记录不覆盖已封存记录；输入或浏览器证据发生变化，需要新的对应审核。
+
+## 成对恢复
+
+HTML 和比较 JSON 通过一个专用私有 journal 发布。短暂看见其中一个文件不表示成对成功；失败或中断后保留真实状态与恢复位置。读取回执的 `transaction.directory` 或诊断中的实际 `recoveryDirectory`，确认属于本次已授权输出后，显式传该目录：
+
+```sh
+"$PD" recover-compare "<确切私有比较事务目录>" --json
+```
+
+未 committed 的事务恢复旧对，已 committed 的事务只清理本事务临时物。后来修改、重建目录、未知 claimant 或备份变化均保留并报告 `recovery-required`，重复恢复同一事务应幂等。stdout 丢失时，在原输出父目录只读定位 `.phoenix-diagram-compare-<id>` 并核其目标；多个候选须明确选择，不按修改时间推定，不改记录或删除备份强行通过。恢复只处理文件事务，不自动补浏览器或实际看图通过。

package/skills/phoenix-diagram/references/authoring-defaults.md

@@ -0,0 +1,42 @@
+# 创作默认值
+
+新稿写 candidate 前读一次；已有候选仅在修复需要改变创作决策时读取。以用户材料和匹配 schema 为准，示例不是可复制的私人事实。
+
+## 事实与修复
+
+保留所有必要责任、实体、关系方向、协议、同步/异步行为、条件、waiting 与恢复路径。关键审批、授权或状态条件放在受影响节点或边上，卡片补充解释；资格条件不能替代批准结果，进入审批也不能替代批准后执行。例如，材料给“合并前可撤回”时，图中单独表示的批准阶段或获批后尚未合并的阶段也要保留撤回路径，不能在审批通过时提前结束这项许可。节点 `tag`/`sublabel`、卡片标题与条目同样只写有依据的事实，不从组件名称推定任务执行方式；可省略的无依据标注直接省略，不追加问题。组件的用途同样须有材料依据，不能按常见用法补充；例如，材料只给“读写 Redis”时，不标为“缓存”。例如，“超预算还需批准”只说明追加条件；材料未要求具体执行先后时，不补造先后，也不为细化先后追加问题。边界必须有真实隔离、所有权、运行或持久化依据。没有节点、边、来源、卡片或边界配额；需要更多内容时增加有意义的行和页面高度。
+
+关系标签携带动作、协议、数据和方向含义。碰撞时先调整间距、自动路线或标签位置，再在保留意义的前提下改写措辞。schema 允许空标签时，仅可省略两端已完整表达且无新增语义的文字，并解释这一创作选择；不能为修几何删除必要标签。Dataflow 的每条 flow 必须有非空 `label`。
+
+用诊断的 `subject` 定位对象、`evidence` 核对实测、`supportedFixes` 选择允许修复。保持语义清单、用户 pins 与已确认拓扑，只修改相关布局邻域。按实际失败门记录 error 数、历史最佳和停滞计数：首次失败计数0，修复后严格低于该门最佳才更新并清零，否则加1；到2立即停止，即使不再运行命令，也不能修改 candidate 或回退到历史较好版本；不因错误种类变化重置或再试。重建交付或返回已记录门时，沿用该门历史，不因新回执重新初始化；环境失败也不允许无限重试。例如同一门 `6 → 4 → 5 → 4` 的后两轮都未优于历史最佳4，应停止。前门通过后首次进入后门是实际进展，按新门初始化并保留全部门状态，不混算跨门的顶层 error 数；同一 validate 门内，诊断 `stage` 首次由 `input` 变为 `layout` 也按进入后门计。也不额外添加强制摆放或重试轮次。
+
+Workflow 修法写明整图验证通过时，按它列出的全部路径一并修改，一轮修完：撤掉列出的路由 pin；文字容量诊断把列出的全部文字控制在给出的文字单位上限内（CJK 字符记 2），超出部分移入卡片条目而不删除。`input/main-path` 列倒退时，按修法一次调整它列出的全部 `col`。
+
+## 新旧合同
+
+新稿明确写 `meta.input_contract: "phoenix-v1"`，默认 showcase。Workflow 新稿使用 `schema_version: 2`，Lifecycle 新稿使用 `schema_version: 3`；其余八类为 1。ER、类、树、时间线、耗时瀑布只有 `phoenix-v1`，未标记时也按它读取。已有未标记 JSON 保留原字节，按 `legacy-2.17` 验证；不要仅为套用新默认值迁移合同。CLI 的显式 `--input-contract` 覆盖必须与用户已授权的导入意图一致。
+
+读取 `compatibility.coreCompatibility` 与 `compatibility.dispositions`，按[兼容约定](compatibility.md)逐项报告非 `supported` 字段的实际处理与原因，并保留原 JSON；不能将核心兼容通过说成旧展示能力全部复刻，也不能借展示限制删除核心事实。品牌仅在明确请求时按[品牌资源](brand-marks.md)处理，普通编译不联网采集；旧安装移除另需明确迁移授权和确认。`sources` 与 `meta.repository` 交付时按[仓库来源创作](repository-authoring.md)核对。
+
+## 布局
+
+- Architecture：先按真实连接组织主路径与子系统，支线靠近负责节点；保留真实边界及显式坐标。新稿可用 schema 的 grid 字段组织有意义的行，省略无依据的固定 viewBox，先用自动路线。
+- Workflow：保留泳道、条件、分支、回路及 mainPath。跨阶段许可按已加载 SKILL 的创作步骤逐状态核对，不能将先补交、重提等业务动作变为前提；保留等价表达，不要求逐节点直接边。新稿省略固定 viewBox 和手工宽度，让编译器测量标签；已有 v1 固定几何不切成 v2。出现共用通道或箭头拥挤时，按诊断的实测节点与整组相关路线，先给共用起点或终点周围留出独立通道；必要时调整未固定节点的 `col`、`row` 或间距，包括回路起点、多入边的汇合与撤回目标。端点可在图的边缘或内部，以所有相关路线的实测结果为准，不由 mainPath 顺序预定位置；不要为了保留拥挤布局而先叠加端口或通道 pin。自己添加的端口或路线 pins 发生冲突时，撤掉这些约束，让自动路线重新联排相关边，避免继续叠加单边 pins；剩余实测问题再按诊断选择端口或路线。
+- Sequence：保留参与者顺序、消息方向、`y`、同步/异步、return 与完整 notes。新稿省略 `meta.column_fit` 和 viewBox 使用新合同默认布局；旧合同缺省 fixed 保持原样。参与者内部动作放在其真实跨参与者消息的 note 中，不造 self-message。给 note 的实际换行高度留空间，28px 基础消息间距不代表 note 容量；修复时协调后续消息、segment 和 activation，不能删 note 含义。
+- Dataflow：明确每个输入由哪个 producer 实际输出，组合转换应保留独立标注的各路输入。真实存储端使用 `database`，内存计算通过生成它的 `backend` 表达。以 stage/row 网格开始；普通数据用 default，主数据 emphasis，确有策略/PII 含义才用 security，异步批处理才用 dashed。
+- Lifecycle：`mainPath` 列出真实主路径，并显式写出每条 transition；保留退出边的 label、note、variant。等待用 waiting，可恢复失败必须存在真实返回边。不得把终止或无法恢复伪装成 recovery。
+- ERD：表优先，列出每张表的全部物理列，保留源 SQL 类型；字段注释写进类型串（如 `varchar(64)｜客户名`），卡片可解释约束但不能代替字段列表。`key` 写出该列承担的全部角色（如 `["pk", "fk"]`），外键必须带 `entity.attribute` 形式的 `references`。分别核对每端最大基数、最小参与数与引用列可空性：外键不自动证明 `NOT NULL`，“可有多个”不单独证明最小数为零。以已给 SQL 约束、联合主键、显式文字或 Mermaid 端点为依据；已明确的事实直接用，不重复询问或要求另选表现形式。需要表示而缺少依据的最小数/可空性，按 SKILL 的开放问题规则先问并停止，不先生成 candidate、画 `0..N`/`1` 再标“待确认”或用卡片兜底；明确授权拟定规则时仍走建议分支。关系两端各写最大基数；`fromOptional`/`toOptional` 省略或写 `false` 表示该端最小值为1，写 `true` 表示0。两种取值都要有材料依据，省略字段不能表示未知。按已核实的功能域写 `tag`，同域表占一块实心的行、列或矩形格子，不夹无关表；有 tag 的表必须用 `row`/`col`。自引用留作外键列，不画自连边。默认仍用 showcase；大型 schema 停滞时按上文停滞规则报告，可询问用户是否改用 standard，未经要求不先降级。
+- Class：每个类型写 `kind`；只选解释所需的成员，成员不截断，长签名由编译器折行。关系从 `from` 读向 `to`：realization 只能由非接口指向接口，inheritance 不跨接口边界，继承不能成环。超类放在子类上方，用 `row`/`col` 摆放。关系种类与两端数量分别据材料确定：成员可脱离整体存在，不等于整体可以没有成员；“包含多个”也不单独给出数量下界。未给下界时保留“多个”等已有数量含义，不补 `0..*`、`1..*` 等数值或其简写，只省略无依据的可选数值标注。“一个/单个/多个”等文字也属于已给数量；交付前逐条核对这些数量已由关系标签或相应的单值/集合成员明确表达，不能仅以组合符号或创建销毁文字替代。明确数值或 Mermaid 端点照用，不重复询问，也不为可选数量标注追加问题。
+- Tree：恰一个根，其余节点各写一个 `parent`，链接只表示包含，不表达调用或数据流。浅而均衡的分解用 `layout.direction: "down"`，深或叶子多的（如仓库目录）用 `"right"`。`collapsed` 只决定阅读器的初始折叠，导出始终是完整树。
+- Timeline：每个 `at` 是带 `Z` 或 `±HH:MM` 的 ISO 时间；`meta.timezone` 是显示时钟，接受 IANA 名、固定偏移及 ICU 兼容别名，缺省 UTC。本期新增接受 `SystemV/AST4ADT`、`SystemV/CST6CDT`、`SystemV/EST5EDT`、`SystemV/MST7MDT`、`SystemV/PST8PDT`、`SystemV/YST9YDT`；曾因不支持而拒绝的这六区输入可直接重试，不改成近似城市时区。这些说明不是名称白名单，实际接受范围以原生输入门为准。`meta.evidence` 必填：记录到的事件用 `observed`，说明性的用 `illustrative`，不把推测或近似的时间标为 observed。只有日期的记录写在该偏移的 12:00 并设 `precision: "day"`，不在卡片里另作说明。声明 `lanes` 时每个事件都要写其中一个 lane；只按输入画事件，不补缺口。
+- Waterfall：跨度的 `start` 与 `end` 或 `duration` 用同一 `meta.unit`；两者同写时必须一致，没有记录结束的跨度必须 `status: "incomplete"`。`meta.evidence` 只有真实计时（trace、日志、性能剖析）才写 `measured`，否则写 `illustrative`；不从代码结构推断时长，也不为计时去运行项目。请求或父跨度的 `end` 只说明该跨度结束，不自动给出 trace 的精确采集截止时刻；仅由自动扩展或人为固定得到的窗口边界不能作为观测事实。未给精确截止时，不在名称、`detail`、卡片、提示或最终答复中补精确截止时刻或截至该时的精确已观测时长。有记录支持的区间可表达“至少/≥”时长下界：同一 trace 已记录的最晚时刻可给出采集截止下界，采集截止时仍开放的跨度可据其起点到该时刻的差给出时长下界，无须知道精确截止；不能由此补精确截止或最终耗时，缺少可省略的截止说明不追加问题。推导时长比较、极值或排序结论时，以材料已给事实、已知数值或上下界为依据，不能默认未结束跨度短于已完成跨度。材料直接给定的比较事实照用，不为证明它额外索要数值。上下界足以证明时，未知总时长也可参与比较；否则写清仅比较已知完成跨度或明确窗口内片段，不把该结论扩为全部跨度的最终耗时比较。判断无子跨度覆盖的区间时，必须核对相关未结束子跨度；缺少其结束依据就不作零覆盖断言。百分比是相对整体墙钟，父子时长不相加；输入没写依赖时不标关键路径。
+
+只有实测缺陷或用户固定几何要求才添加 route/label pins。自动端口方向是离开/进入边界的方向合同；不得接受穿过无关不透明节点、含混共用通道或标签盖住其他关系的路线。
+
+## 文本与展示
+
+沿用户选择或对话主语言创作，保留原样标识；繁体中文请求写繁体内容。`meta.locale` 只选择 Viewer 固定界面，支持 `en`、`zh-CN`、`zh-TW`、`es`、`ko`（大小写不敏感）；其他标签回退英文界面和 `<html lang="en">`，回执 `locale.fallback` 为 true，需在答复中说明。不翻译作者内容。
+
+省略默认 `meta.visual_preset` 得到 classic；省略 subtitle、legend 得到标题与 truthful auto。其他视觉风格、额外副标题须有用户请求。`engineering_profile` 仅在明确请求且事实已知的部署所有权场景启用，启用后不为过检而删除。
+
+桌面图保持完整可读且无水平溢出；按真实内容增加纵向节奏。只接受 Reader 已声明、浏览器已测量的页面纵向滚动，具体见[交付合同](delivery-contract.md)。禁止裁剪、内部图解滚动或缩小字体来伪造通过。

package/skills/phoenix-diagram/references/brand-marks.md

@@ -0,0 +1,52 @@
+# 品牌资源
+
+仅在用户明确要求品牌标识时使用。品牌只补身份，不能替代组件标签、职责或 type 语义标识；不从组件名称猜品牌或官方网站。明确要求标识不等于授权联网采集；只有用户明确要求采集、并给出公共 HTTP(S) URL 时才运行 capture。
+
+命令沿主 SKILL 中已解析的 `PD`，从用户工作目录执行。普通 validate/deliver/finalize/compare/preview 只读取固定目录或已固定的本地缓存，不联网补资源，不隐式安装或更新引擎。
+
+## 离线查询与使用
+
+```sh
+"$PD" brands "<用户指定的品牌查询>" --json
+```
+
+省略 query 列出固定目录；查询匹配 ID、title、category、aliases、domains 的子串。返回 `catalogVersion`、`query`、`matches`、`diagnostics`，每个 match 有 `id`、`title`、`category`、`aliases`、`domains`、`provenance`。空 matches 就是无匹配，不能按相似名称换成别的品牌。
+
+无目录匹配且用户未提供官方 URL 时，省略这项可选品牌标识，保留原职责、标签并说明未加入标识；不猜站点、不下载，也不为可选品牌扩展业务澄清。已有输入明确固定 brand 而资源缺失或变更时，按真实诊断失败，不能删除该字段来过检。
+
+在原图对应元素的 `brand` 字段使用已核实的 canonical ID。原五类的支持位置为 architecture.components、workflow.nodes、sequence.participants、dataflow.nodes、lifecycle.states；ER、class、tree、timeline、waterfall 不扩加 brand 字段。在brand输入或capture中，已知目录域名的HTTP(S) URL可离线解析为内置品牌，仍优先使用回执给出的ID；brands查询本身只做上述子串检索。
+
+## 明确采集官方 URL
+
+先把 `OFFICIAL_URL` 设为用户给出的实际 URL，`BRAND_CACHE` 设为本次选择的缓存目录；不执行含占位符的命令。
+
+```sh
+"$PD" brands capture "$OFFICIAL_URL" --brand-cache "$BRAND_CACHE" --json
+```
+
+省略 `--brand-cache` 时，缓存为当前工作目录下 `.phoenix-diagram/brands/v1`。成功后把回执的 `brand` 值原样用于对应元素：
+
+- 已知目录域名：`brand` 为字符串 ID；使用内置向量，零网络，`cachePath` 为 null。
+- 其他获准 URL：`brand` 为 `{ "url": "…", "sha256": "…" }`；URL 与64位小写 SHA-256 必须一起固定，后续编译使用同一缓存目录。
+
+`brand` 不是整个回执，不把 `resource`、`cachePath` 或 dataBase64 填入输入。未知 URL 的裸字符串不会触发采集，也不能通过删除 brand 来绕过失败。资源变更时，只在已获明确采集授权的范围内重新采集并交接新的摘要；不静默刷新。
+
+CaptureReceipt 的公共头为 `schemaVersion/tool/toolVersion/command/status/diagnostics`，command 为 `brands capture`，status 为 pass/failed；另有 `brand`、`resource`、`cachePath`，失败时不返回已激活资源。`resource` 包含 `id/sha256/bytes/mediaType/urlSha256/sourceUrl/resolvedUrl/catalogVersion`；不适用项可为 null。公共来源和 HTML 内资源事实去掉 URL query/fragment；消费缓存仍按 capture 返回的 brand 身份，不自行改写 URL 或摘要。
+
+网络仅读取指定 URL、受检查的重定向，以及该页 head 明确声明的 HTTP(S) 图标链接或 favicon；声明的 CDN 图标也逐请求检查，不另行发现其他品牌网站、不执行页面脚本。只收 MIME/签名/尺寸/边界相符的 PNG、JPEG、WebP、ICO；网络 SVG 不接受，可信内置向量仍走离线路径。总期限8秒，HTML head上限256KiB，图像1MiB、宽高各不超过4096；安全限制不能用私网开关、代理或随意换图绕过。userinfo、非标准端口、私有/回环/保留地址及不安全 DNS 结果均拒绝。
+
+## 诊断与交付
+
+| code | 处理 |
+| --- | --- |
+| `brand/unknown` | 核对用户指定身份和目录结果，不猜替代品牌。 |
+| `brand/unpinned-url` | 未固定的非目录 URL；仅获明确授权后采集。 |
+| `brand/cache-missing` | 同一 URL/摘要的安全缓存不可用；不在普通生成中联网。 |
+| `brand/digest-mismatch` | URL、摘要或缓存身份不符；保留现有材料，核对原回执。 |
+| `brand/blocked` | URL/DNS/IP安全边界拒绝，不绕过。 |
+| `brand/capture-unavailable` | 资源或网络不可获得，报告实际缺口，不换来源。 |
+| `brand/invalid-image` | MIME、字节、尺寸或边界不符，不冒充已采集成功。 |
+
+品牌失败的退出码区分输入/策略1、归属冲突3、I/O4、资源或缓存不可获得5；参数错误为2，仍须读 diagnostics。图标占用标题轨容量，固定几何不足应修获准几何或报告诊断，不缩字、删标签或改用户 pins 过检。
+
+继续正常 finalize、实际打开当前截图、review-record，并回读同一 summary；采集成功不代表图解或来源整体已通过。保留主 SKILL 的强事实规则、语言选择和同一失败门两次停滞即停止的规则；品牌请求不授权补造业务事实。

package/skills/phoenix-diagram/references/compatibility.md

@@ -0,0 +1,22 @@
+# 输入与展示兼容
+
+导入已有 JSON 或解释兼容回执时读取。本约定不授权改写原输入、迁移安装或替用户补事实。
+
+| 输入 | 合同 |
+| --- | --- |
+| 新稿，全部十类 | 明确写 `meta.input_contract: "phoenix-v1"` |
+| 未标记的 architecture、workflow、sequence、dataflow、lifecycle 旧稿 | `legacy-2.17`，保留原字节及默认几何 |
+| 已知来自 Archify 3.1 的原五类稿件 | 显式传 `--input-contract phoenix-v1`，不为导入改写原文件 |
+| erd、class、tree、timeline、waterfall | 只有 `phoenix-v1` |
+
+显式合同、质量参数与输入已有声明冲突时会拒绝；不能通过覆盖参数消除已声明的语义。五份 `examples/legacy.*.json` 保留固定 2.17 原例字节，只供兼容输入使用，不是新稿默认值。
+
+读取 deliver 阶段的 `receipt.compatibility`，不要仅看退出码：
+
+- `coreCompatibility` 表示核心输入兼容结果，不能证明旧 Reader 的全部展示能力已复刻。
+- `dispositions` 按 JSON pointer 给出 `path`、`disposition`、`reason`。`brand` 为 `supported`，由固定目录或摘要固定的本地资源解析；缺失资源仍须按实际诊断处理。
+- `/meta/views` 为 `unsupported-display`：旧 Guided Views 不重建，当前 Reader 提供导航。
+- `legacy-2.17` 的 `/meta/animation` 为 `ignored-display`：旧播放偏好不覆盖首次 Still。
+- 有非 `supported` 项时 `status` 为 `partial`；这些是终局处理，`deferredFields` 为空，不再承诺某个后续阶段补齐。
+
+在交付答复中逐项说明非 `supported` 字段及原因。保留原 JSON 和已有独立 HTML，不把不支持的展示改成卡片、删掉必要事实或宣称全量兼容。仓库来源核对、时间证据及语言回退仍分别按各自回执交接。

package/skills/phoenix-diagram/references/delivery-contract.md

@@ -0,0 +1,127 @@
+# 交付与实际审核
+
+读本文件处理 finalize、诊断、实际图像审核、review-record、环境失败或输出恢复。用户明确请求双输入架构比较时，使用[架构比较合同](architecture-compare.md)的三视图、独立两门 summary 和 12 图观察记录；本文件下方的单图四门与四图记录保持原合同。命令使用 `SKILL.md` 中已解析的 `PD`，从用户工作目录执行。
+
+## 四门与身份
+
+```sh
+"$PD" finalize <type> candidate.json diagram.html --json
+"$PD" finalize <type> candidate.json diagram.html --repo-root "<仓库根>" --json
+```
+
+带 `sources` 或 `meta.repository` 的图用第二种，单图的 `--repo-root` 接受 `validate`、`deliver`、`finalize`；双输入架构比较另由 `compare --repo-root` 处理。来源核对独立于四门：回执与 summary 的 `evidence.status` 为 `verified`、`partial`、`unverified` 或 `none`，校验与交付回执另列 `evidence.unverified`（pointer、元素、原因）与 `evidence.unsourced`。结构错误（凭据 URL、路径逃逸、非法行区间、provider 与主机不符、网页链接用了不支持的主机）在 input 阶段失败且不生成 HTML。
+
+固定顺序为 `validate → deliver → check → browser-check`。首个非 pass 阶段后其余阶段保持 `not-run`。`validate` 做输入/布局与独立 artifact 检查；`deliver` 发布本次 HTML；`check` 严格绑定当前交付；`browser-check` 检查浏览器实测并采集当前截图。读取每个阶段真实 status，不能补造通过。
+
+stdout 是单一 JSON。保留首次成功自动验收的 `deliveryReceiptId`、`browserReceiptIdentity`、`candidate` / `artifact` 的 `path` 与 `identity:{sha256,bytes}`、`configSha256` 和完整 `engine`。HTML 已提交不等于整体完成；自动四门通过后，`visualReview.status` 仍为 `required-pending`，`deliveryStatus` 为 `incomplete`。finalize 回执的 `locale` 给出请求、解析后的界面语言与是否回退英文。
+
+从 `evidence.summaryReceipt.path` 或 `evidence.summaryPath` 定位本次 summary，从 `evidence.browserReceipt.path` 读取绑定的浏览器回执。summary 在输出旁，`--out-dir` 指定截图/浏览器证据目录；按回执给出的真实路径读取，勿猜测文件名或跨图混用。
+
+失败时使用当前 summary 的 diagnostics。`producedByThisRun: false` 或 validate/deliver 未过时，不对输出路径执行视觉验收：该路径可能仍是旧的 last-good 文件。修复 candidate 后重新 finalize，使用新的 `--out-dir` 留存新证据；原 candidate、HTML、配置、引擎或截图身份变化后，旧审核不能继承。仅为取完整状态或登记看图结果不得再次 finalize。
+
+## 浏览器与实际看图
+
+自动检查覆盖 1440×900、1600×1000、1920×1080、2048×1320 桌面；实际审核使用回执中的四张截图：1440×900 与 2048×1320 各 light/dark。打开每张当前图片，检查主图、全部标签/notes、卡片、关系遮挡、层级和控件。截图文件、digest、DOM 数值或测试输出都不代表已经观察。
+
+每个桌面尺寸必须无水平溢出。纵向滚动仅按 Reader 声明和测量接受：`intrinsic-height` / `width-first` 的自动画布，或 Architecture 显式 viewBox 的 `authored-height`，需完整内容留在 panel 内，无内部滚动或裁剪，页面允许纵向滚动，且回执确认可读并给出 `verticalScrollAccepted: true` / `overflowDisposition: "readable-vertical-scroll"`。未知声明、水平溢出、不可读文字和 chrome 遮挡仍失败。不能手工改 DOM 属性伪造该例外。
+
+定向诊断可用下列公开命令；它们不替代同一交付的四门 summary：
+
+```sh
+"$PD" validate <type> candidate.json --quality showcase --layout-json --json
+"$PD" check diagram.html --strict-provenance --json
+"$PD" browser-check diagram.html --out-dir evidence-2 --json
+"$PD" visual-check diagram.html --out-dir evidence-3 --json
+```
+
+环境 `unavailable`、执行或断言 `failed`、后续 `not-run` 与未实际看图必须分别报告。自动门失败先修该门；没有图像能力时不得从测量推测 `passed`。不自动安装引擎或浏览器，也不打开用户现有浏览器、启动 preview。
+
+## 生成完整审核草稿
+
+以下命令只从**当前自动四门已通过**的 summary/browser 回执复制身份，创建一个新文件。先将 summary 和 review 路径换成真实路径。Node.js 18+ 即可运行，不需要仓库或 Rust。它不会替你看图，草稿中的空 reviewer、`observed: false` 和 `verdict: "unavailable"` 必须按实际情况处理；`status: "pass"` 是记录协议字段，不是视觉通过。
+
+```sh
+node - "<当前summary路径>" "review-01.json" <<'NODE'
+const fs = require('node:fs');
+const [summaryPath, recordPath] = process.argv.slice(2);
+const summary = JSON.parse(fs.readFileSync(summaryPath, 'utf8'));
+const names = ['validate', 'deliver', 'check', 'browser-check'];
+if (summary.automatedStatus !== 'pass' || summary.stages.length !== 4
+    || !names.every(name => summary.stages.filter(stage => stage.name === name && stage.status === 'pass').length === 1)) {
+  throw new Error('The current four automated gates must pass before review.');
+}
+const browser = JSON.parse(fs.readFileSync(summary.evidence.browserReceipt.path, 'utf8'));
+if (browser.screenshots.length !== 4) throw new Error('Four current screenshots are required.');
+const bound = file => ({ path: file.path, identity: file.identity });
+const record = {
+  schemaVersion: 1,
+  tool: 'phoenix-diagram',
+  toolVersion: summary.toolVersion,
+  command: 'review-record',
+  status: 'pass',
+  diagnostics: [],
+  artifact: bound(summary.artifact),
+  candidate: bound(summary.candidate),
+  configSha256: summary.configSha256,
+  engine: summary.engine,
+  deliveryReceiptId: summary.deliveryReceiptId,
+  browserReceiptIdentity: summary.browserReceiptIdentity,
+  screenshotIdentities: browser.screenshots.map(screenshot => ({
+    file: bound(screenshot),
+    viewport: screenshot.viewport,
+    theme: screenshot.theme,
+    observed: false,
+    observations: ''
+  })),
+  reviewer: '',
+  scope: ['diagram', 'labels', 'cards', 'relationship-occlusion', 'hierarchy', 'controls'],
+  verdict: 'unavailable',
+  findings: ['Image review has not been performed.']
+};
+fs.writeFileSync(recordPath, JSON.stringify(record, null, 2) + '\n', { flag: 'wx' });
+NODE
+```
+
+实际打开四张图片后，填写真实 reviewer；逐张写 `observed: true` 和非空 `observations`，描述实际看到的上述六类内容。无缺陷才能设 `verdict: "passed"`、`findings: []`；有缺陷用 `failed` 并列具体 findings。确实没有图像工具/审核者时使用 `unavailable`、真实 reviewer 标识与非空限制说明，保持未完成。不要新增未知 JSON 字段、改身份、改 viewport/theme 或把观察复制到未打开的截图。
+
+## 原身份收口
+
+```sh
+"$PD" review-record diagram.html --record review-01.json --json
+```
+
+读取返回的 `evidence.summaryReceipt.path`，再读该交付的当前 summary。核对四门全部 pass、`automatedStatus: "pass"`、`visualReview.status: "passed"`、`deliveryStatus: "complete"`；`deliveryReceiptId`、`browserReceiptIdentity`、输入/HTML/配置/引擎绑定须与首次审核材料一致。仅凭 review-record 退出码或截图存在不能称完成。
+
+相同已封存记录可幂等重试；若记录已保存但 summary 写失败，保留同一记录字节并重试 review-record。不要再次 deliver/finalize 取得另一个身份，也不要覆盖已封存的不同记录。用户要求或实际缺陷导致改 candidate 时，生成新交付和新证据，再做对应审核。
+
+## 输出恢复
+
+`commitState` / diagnostics 表明 `recovery-required` 时，报告实际 public 文件状态及保留记录。在原输出父目录执行 `ls -la "<原输出父目录>"`，只读核对记录中的 target。设原输出父目录为 `P`、记录内 transactionId 为 `ID`，同一事务的记录可能处于以下三处：
+
+1. `P/.phoenix-diagram-recovery-ID/publication-recovery-v1.json`。
+2. 清理中的 sibling witness：`P/.phoenix-diagram-recovery-ID.cleanup.json`。
+3. 最后清理 quarantine：`P/.phoenix-diagram-output-cleanup/ID.json`。固定目录为当前用户 0700，保留自身绑定的 0600 `owner-v1.json`；有效 owner 的空壳允许保留，不等于 pending。
+
+对已授权、与本次目标绑定的事务，**始终显式传原 recovery-ID 目录，即使该目录已不存在**。不能把 witness 或 quarantine JSON 路径当作参数；命令只从这个原目录路径导出同 ID 的另外两处记录。
+
+```sh
+"$PD" recover-output "P/.phoenix-diagram-recovery-ID" --json
+```
+
+将 P/ID 换为已识别的真实值。多个记录必须明确选择，不扫描后自动挑事务，不按目录时间推断。未知 owner、额外条目、替换对象或多处记录歧义均保留拒绝；不得删除、移动或重写它们来强行通过。
+
+读取返回的 `publicState`、`preserved`、`recoveryStatus`、diagnostics 和退出码。原目录不存在但可信 witness/quarantine 记录仍在时须继续由命令验证，不能自行宣称 absent。恢复只处理文件事务，仍需适用的交付检查与实际图像审核；后来的 claimant 或绑定改变应被保留并如实报告。
+
+## 架构比较的独立收口
+
+仅明确的架构比较请求使用以下顺序，完整约束和可复制的审核草稿见[架构比较](architecture-compare.md#创建完整审核草稿)：
+
+```sh
+"$PD" compare architecture base.json head.json comparison.html --json
+"$PD" check comparison.html --strict-provenance --json
+"$PD" visual-check comparison.html --out-dir compare-evidence-01 --json
+# 从返回的 evidence.summaryReceipt / evidence.browserReceipt 读取原件，实际观察 12 张图并填写完整记录。
+"$PD" review-record comparison.html --record comparison-review-01.json --json
+```
+
+比较 summary 的 `comparison` 绑定原比较回执、双输入、配置/资源/引擎、IR 与 HTML；stages 仅为真实 `check`、`visual-check`。三个视图的 12 张当前图片均须观察。自动通过仍为 `required-pending` / `incomplete`，只有该 summary 的自动两门与实际审核通过才 `complete`。不要用单图记录、原 compare JSON 或重新生成成果代替这份可变收口摘要。

package/skills/phoenix-diagram/references/extending-types.md

@@ -0,0 +1,14 @@
+# 增加图型
+
+仅在维护者明确要求扩展工具时读取。普通作图不扩展引擎；当前支持十类，未知类型继续返回 `input/unsupported-type`。
+
+一个新类型须同时交付以下路径，不能只增加 schema 或模仿已有 SVG：
+
+1. **输入与语义**：定义类型标识、合同、schema/common 引用及完整语义校验；保持现有十类和两种合同的解释。新能力不能静默改变旧输入默认值或原 JSON。
+2. **发现与创作**：同步 `DiagramType`、CLI/guide、包内 schema 与完整最小示例、skill 图型映射及必要创作规则。明确与相邻类型的边界，未知类型仍拒绝。
+3. **布局、渲染与检查**：实现类型布局、结构化图元、独立 HTML、语义/几何/文字检查和可操作 diagnostics。保持标签、关系、数量、来源与用户 pins；不加内容配额或通过裁切、缩字、隐藏来过检。
+4. **Reader 与导出**：为适用的选择、详情、搜索、图关系、相机及范围操作提供真实 graph 数据；不适用的能力明确禁用。覆盖主题、Still/Live、键盘、五语言/回退、移动端与各导出路径，保留离线字体及许可。
+5. **交付与分发**：接入 finalize、浏览器检查、实际看图及 review-record 身份链；纳入 sourceInputs、bundle manifest、安装允许成员、npm tgz、来源与完整许可。不把运行期依赖转成下载源码、Node renderer 或未声明资源。
+6. **回归**：以有辨别力的正常、边界、错误输入和完整事实用例验证新类型；同时验证既有十类、CLI、两种合同、已有独立 HTML/Reader、离线与安装边界。自动检查和实际看图分别记录，未运行的环境不计通过。
+
+类型扩展不自动扩展架构比较、品牌采集、预览或迁移的授权范围。同步所有复述类型/命令的当前接口文档，保留冻结 oracle、历史记录与第三方文本；按构建流程重建 bundle，不能只更新 skill 源文件。

package/skills/phoenix-diagram/references/migration.md

@@ -0,0 +1,57 @@
+# 项目级旧入口迁移与回滚
+
+仅在用户明确请求迁移所选项目的旧 Archify 入口时使用。先展示精确移除范围和不备份后果，只有覆盖该范围的明确确认才进入apply；已有明确授权不重复询问。普通install或普通作图不授权迁移。迁移保留原JSON、已有独立HTML以及范围外内容，不接管个人目录、Phoenix UI、共享settings/hooks或其他provider。
+
+旧skill是确认后直接移除，**没有目标备份**。固定历史源码是识别与显式重装依据，不是用户旧目录的备份。回滚只处理新Phoenix Diagram受管写入，不自动恢复已删除的Archify。
+
+## 查看范围，再确认执行
+
+沿主 SKILL 使用当前加载的 `PD`。`PROJECT` 是用户明确指定的实际项目目录，不从个人安装位置推定。skill launcher会为from-archify补入配套包内bundle-root；若直接运行原生引擎，必须显式给配套 `--bundle-root DIR`。
+
+```sh
+"$PD" migrate --from-archify --project "$PROJECT" --providers claude,codex --dry-run --json
+# 仅在用户已确认上面精确范围及无旧备份后执行：
+"$PD" migrate --from-archify --project "$PROJECT" --providers claude,codex --confirm-remove-archify --json
+```
+
+`--providers` 可省略：按项目已存在的已知provider目录选择；都没有时默认claude。选择codex会同时检查.agents与.codex的旧入口，新Diagram skill只写入.agents；最终以回执providers和逐项路径为准，不把示例的两个provider当全部支持名单。
+
+dry-run只报告计划与冲突，零写入；遇pending只报告，不恢复。检查 `status`、`project`、`providers`、`migrationSources`、`removals`、`preserved`、`legacyBackupPolicy`、`reinstallInstructions`。只识别完整匹配固定来源、没有外部管理归属且物理快照稳定的项目副本；自定义/多缺文件、链接、未知来源、外部管理或个人安装应保留，不能为了过检强删。
+
+实际apply必须带 `--confirm-remove-archify`；缺少时是 `install/confirmation-required`、exit3，删除与新入口写入都不开始。确认仅限所展示的项目/provider/目录，不授权清理其他位置。先持久化事务意图、确认范围与快照，再逐项受检查移除旧文件并发布新入口，active最后提交。没有跨整个过程的“失败就零变更”承诺；中断时交接真实已删、剩余和保留项。
+
+联合安装的 `--migrate-archify` 属于独立的联合安装器入口，不是给 `PD migrate` 添加的参数；它先展示原生dry-run；TTY肯定答复才apply，拒绝/EOF不开始，非TTY必须显式确认标志。`--no-phoenix-diagram`仍跳过并保留旧入口；迁移分支提前返回，不进入hooks/settings/AGENTS/UI安装。仅给确认标志不构成迁移请求。
+
+## 指定事务恢复或回滚
+
+从本次回执取得真实 `transactionId`、`recoveryCommand`、`rollbackCommand`，优先原样使用绑定本项目的命令，不扫描后自动挑一个事务。三种mode互斥：
+
+```sh
+"$PD" migrate --recover "$TRANSACTION_ID" --project "$PROJECT" --json
+"$PD" migrate --rollback "$TRANSACTION_ID" --project "$PROJECT" --dry-run --json
+"$PD" migrate --rollback "$TRANSACTION_ID" --project "$PROJECT" --json
+```
+
+若部分回滚已恢复旧 launcher/ENGINE，旧引擎可能不支持 migrate；使用原回执给出的已验证新原生引擎 recoveryCommand，不换成旧 launcher，也不按 PATH 猜引擎。
+
+recover不接受dry-run；recover/rollback都不接受bundle-root、providers或confirm-remove-archify。它们核已存在的固定正确引擎与本地事务，不下载、不更新、不重装旧skill，不要求当前active安装已完整提交。
+
+普通 install 的 pending 恢复仍按其回执重跑原显式 install；`migrate --recover ID` 用于已确认的迁移或正在回滚的指定事务，不能代替普通安装恢复。优先执行对应回执的 `recoveryCommand`，不要只因有 journal ID 就改用迁移恢复命令。
+
+- Recover继续指定已确认事务的安全剩余步骤；同一确认范围不重复索取确认。后来新增/改写、删除后重建或父目录身份变化保留并报告recovery-required；不凭stdout推断哪些文件已删。
+- Rollback仅回滚**当前committed事务**的新入口受管写入；包括仍为v1的当前事务经原生引擎验证并扩展后的回滚，不是跳过后来安装去回滚任意历史ID。后来修改在预检时冲突，先保持零变更；中途身份变化仍保留拒绝。成功rolled-back，同一ID可幂等重试。
+- 恢复之前的Diagram active语义须重新绑定恢复后的实际文件身份/checksum；不手拷旧active、journal或备份内容。Archify删除不逆向恢复，按回执reinstallInstructions另获授权后显式重装。
+
+## 回执与后续检查
+
+InstallReceipt公共头为 `schemaVersion/tool/toolVersion/command/status/diagnostics`。migrate的status使用 planned/installed/unchanged/conflict/recovery-required/recovered/rolled-back等安装状态，不按普通图解pass解释；cancelled只用于真实取消，不能把中断或失败写成取消。冲突/recovery-required为exit3，参数2、I/O4；仍读逐项诊断和实际结果。
+
+重点交接：
+
+- `transactionSchemaVersion` 与外层 `schemaVersion` 不同，不能据外层1推断journal仍为v1。
+- `transactionId/journal/recoveryCommand/rollbackCommand` 定位实际事务，`engine`与manifest摘要绑定来源。
+- `removals`逐项含 `path/source/status`，区分planned/removed/preserved/remaining；同时读 `preserved/conflicts/recovered/writes/unchanged`。
+- `legacyBackupPolicy: "none"`、`legacyRestoration: "not-supported"`、`reinstallInstructions`明确旧skill不恢复；`backup`仅涉及Diagram受管写入，不能称为Archify备份。
+- `reloadSteps`要求新建provider会话并核实际加载phoenix-diagram路径。外部/个人旧入口未处理时，不声称全机唯一入口生效。
+
+迁移成功不代表既有图像已重新验收；需要新交付时仍保留主 SKILL 强事实、语言、Still、两次停滞即停止及 mandatory visual，不因更换入口删事实或降低验收。

package/skills/phoenix-diagram/references/preview.md

@@ -0,0 +1,45 @@
+# 显式本地预览
+
+只有用户明确要求本地预览才启动前台服务。普通作图不启动 preview；启动预览也不自动授权打开用户浏览器窗口。只有用户希望打开窗口时才加 `--open`。预览不充当正式交付或实际图像审核。
+
+沿主 SKILL 设置 `PD`，使用事实齐备的现有 candidate，不为预览重新猜测或改写输入。首次阅读仍为 Still，Live 由用户主动选择；不采用旧入口的默认 Live。
+
+## 启动与事件
+
+```sh
+"$PD" preview <type> candidate.json diagram.html --port 0 --json
+# 用户同时明确希望打开窗口时：
+"$PD" preview <type> candidate.json diagram.html --port 0 --open --json
+```
+
+支持现有十类。可加 `--quality standard|showcase`、`--input-contract legacy-2.17|phoenix-v1`、`--repo-root DIR`、`--brand-cache DIR`；合同适用类型和声明冲突规则沿普通编译。repo-root 须为现有目录，来源是否 verified 仍单独核对。preview 不接受 `--out-dir` 或 `--layout-json`。品牌只消费本地固定资源，服务不隐式联网补品牌。
+
+固定监听127.0.0.1，默认 port=0由系统分配；`--port` 范围0–65535。未加 `--open` 时从 started 读取 URL。stdout 是前台 NDJSON，每行一个事件，不能把多行整体当单个 JSON，也不能在第一条 updated 后把仍运行的进程当已停止。
+
+| event | 含义 |
+| --- | --- |
+| `started` | 会话/监听已建立；额外给 `url`、`port`，不表示已有成功图。 |
+| `checking` | 正在检查当前 generation。 |
+| `updated` | 当前结果已正式发布并回读，HTTP artifact与正式文件同字节。 |
+| `failed` | 本次尝试失败；可能继续等待修改，不能把该事件直接当进程已退出。 |
+| `stopped` | 停止结果；核 `shutdownComplete` 与 `exitCode`，不只看事件名。 |
+
+每条事件有公共头 `schemaVersion/tool/toolVersion/command/status/diagnostics`，command 为 preview；另有 `event/sessionId/generation/lastSuccessfulGeneration/lastAttemptStatus/artifact/artifactAvailable/locale/browserStatus/visualReviewStatus`。event 与 status 不同：status可能为 waiting/checking/ready/error/stopped；lastAttemptStatus可能为 not-run/checking/pass/failed/cancelled。failed与stopped事件另给真实 exitCode；shutdownComplete仅 stopped 给出。
+
+首次 generation/lastSuccessfulGeneration为0、artifact=null、artifactAvailable=false。artifact可用时给 `generation/inputSha256/sha256/bytes`；后两个是正式 HTML 的摘要和字节数。browserStatus与visualReviewStatus保持 not-run，不能由updated推出浏览器或看图通过。
+
+## 修改、last-good与冲突
+
+输入按800ms轮询、400ms稳定窗口处理；内容摘要或不可用/删除状态变化产生新 generation，同字节不重复推进。单worker和最新待处理槽保证旧结果不能倒退覆盖新结果。
+
+半写、非法或删除输入时保留最后成功文件。shell在画布外显示最新失败、诊断和仍显示的成功版本；首个成功之前为waiting/error，即使输出路径原本有文件，也不冒称本会话已有成功图。修复后只有最新且仍绑定原输入/资源的结果才发布。
+
+输出被后来替换时停止发布并报告冲突，不能拿内存旧图冒充正式路径的当前文件；不能覆盖外来文件来继续演示成功。需要输出恢复时按 diagnostics 指明的精确事务和现有 recover-output 合同处理，不自行选记录、删除锁或重建恢复材料。
+
+服务仅提供该随机会话路径下 GET/HEAD 的shell、status、artifact；URL直接取started，不猜路径。Host/Origin受检查，无CORS或任意文件服务，响应no-store/no-referrer。正式HTML/导出不混入会话端口、token、输入绝对路径或错误栈；连接断开不等于视觉通过。
+
+## 停止与正式交付
+
+用Ctrl+C或SIGTERM停止前台会话，只结束自己的监听、连接与worker；等停止事件并确认shutdownComplete=true。最后成功正式文件保留。SIGKILL没有正常收尾回执，不能补写stopped或关闭通过；留下的发布事务仍按原恢复入口检查，不杀未知PID。
+
+停止后按普通 finalize、实际查看当前四张截图、review-record 和同一 summary 收口。已有HTML、HTTP可打开或updated都不能代替四门与 mandatory visual。预览期间的编辑不重置同一失败门的历史最佳和停滞计数；达到2后停止继续修 candidate，按主 SKILL 交接未解决项。服务不授权补造事实、删除语义或改语言原则。

package/skills/phoenix-diagram/references/repository-authoring.md

@@ -0,0 +1,29 @@
+# 仓库来源创作
+
+图要解释真实仓库时读本文件。源码是职责、调用、边界与持久化的依据；请求的含义全部覆盖、每条断言都有来源支持时，图才算完成。只读用户指定的仓库与切片，不全仓扫描，不 fetch、不改仓库，也不调托管 API。
+
+## 按需阅读
+
+1. **固定身份。** 在目标仓库记录 `git rev-parse HEAD`、`git remote get-url origin` 与 `git status --short`。origin 若含 HTTP(S) 用户名、密码或 token，先去掉再写入 candidate（工具会拒绝带凭据的 URL）；保留其传输方式、端口、路径与 `.git` 后缀，不把内部 SSH 地址改写成 HTTPS。把去凭据的 URL 与 40 位提交写进 `meta.repository`。SSH origin、非 GitHub/Gitee/GitLab 托管、只需本地链接或测试用仓库时设 `link_mode: "local-only"`；只有 GitHub、Gitee、gitlab.com 或声明 `provider: "gitlab"` 的自管 GitLab HTTPS 地址能生成网页链接。来源按固定提交的已提交字节核对，不按工作树：工作树有改动时，工具对与固定提交不同的被引文件记 `worktree-differs`，答复中仍须列出这些改动路径。
+2. **划定切片。** 用项目说明、manifest、入口、注册与部署配置定位相关运行单元，读入口、配置和与请求相关的模块。沿 import 与调用点追到该职责实际的输入、输出或副作用；读一小段相连的切片，不为找方便的标签扫描整个仓库。
+3. **追踪归属。** 运行与 I/O 关系取自调用点上实际的执行者、操作和目标；部署与信任关系取自对应配置或执行处。区分发起操作的控制者、执行它的运行时和接收字节的存储。文件或数据库边的来源必须指向实际读写者；“负责维护任务”之类的职责描述不能证明直接 I/O。已配置的提供方、注入的适配器、本地 stub 与持久服务是不同断言，只标来源支持的那一个。
+4. **边读边记来源。** 每个组件和重要关系记下仓库相对路径与闭区间行号。沿实际分支、重试、回退与错误处理走；导出或配置了但正常路径不调用的函数是可选能力，不是必经边。关于权威状态变更或控制归属的断言，要追到实际写入或执行处及其允许条件。
+5. **写明不确定。** 把未解决的问题写在受影响的断言旁，例如“这里调用了 `writeFile`，持久性未知”。继续读下一段相关源码解决它，或作为明确的未知保留；不把标签、包描述或配置值变成未观察到的服务或行为。
+
+每个请求的职责、关系与边界都有来源支持，剩余未知不会改变这一覆盖时停止阅读。没有节点、边、引用或卡片数量目标。用带原始行号的方式读源码（如 `nl -ba <file> | sed -n '40,90p'`），从显示的行号抄写引用起止行；摘录读到文件末尾时写实际末行。
+
+## 各图型的来源
+
+只有主要元素写 `sources`，每个至多三段：Architecture 组件，Workflow、Dataflow 与 Tree 节点，Sequence 参与者，Lifecycle 状态，ERD 实体，Class 类型，Timeline 事件，Waterfall 跨度。关系、消息、流与转换没有来源：把调用、写入或转换处引在拥有它的元素上（调用方、写入方、离开的状态），其余依据写进 note 或卡片。目录节点引用自己的 README 或入口文件，否则引用定义或运行它的文件。
+
+Timeline 事件引用固定提交里记录它的文件（如 changelog 条目），时间取自该历史中的 tag 或提交；只有日期的记录写在该偏移的 12:00 并设 `precision: "day"`。不在该历史中的 tag 或提交不能引用。没有记录 trace 的 Waterfall 用 `meta.evidence: "illustrative"`，时长保持示意标注，不为计时去运行项目。
+
+## 交付与答复
+
+```sh
+"$PD" finalize <type> candidate.json diagram.html --repo-root "<仓库根>" --json
+```
+
+`--repo-root` 必须是该仓库的顶层目录。核对只读：校验 origin 与声明一致、固定提交存在、被引文件与行在该提交中存在，并逐段比较工作树文件（不跟随符号链接）。缺少 `--repo-root`、git 不可用或超时、提交或对象缺失、文件缺失、行越界、工作树不同，或旧版 git 遇到部分克隆时，对应来源记为待核实并附原因；HTML 照常生成，来源状态不改变四门结论和退出码。
+
+读回执 `evidence.status`：`verified` 表示全部来源已核对且每个主要元素都有来源；`partial` 表示部分核对；`unverified` 表示零条核对；`none` 表示没有声明仓库也没有来源。答复中列出待核实元素及原因、未提供来源的元素和工作树改动路径，不把非 `verified` 的图称为已核对。工具只证明“路径与行在固定提交中存在，且作者读到的工作树与之相同”；引用内容是否支持断言，由作者按上文纪律负责。