@xenonbyte/da-vinci-workflow 0.2.1 → 0.2.3

package/docs/zh-CN/pencil-rendering-workflow.md

@@ -31,7 +31,7 @@ PNG 只是审查产物，不是设计真相源。
 Da Vinci 现在要求自治运行使用这组 session wrapper：
 
 - `da-vinci pencil-session begin`
-- `da-vinci pencil-session persist`
+- `da-vinci save-current-design`
 - `da-vinci pencil-session end`
 
 这组 wrapper 的作用，是把下面三件事变成强制步骤：
@@ -77,18 +77,21 @@ Da Vinci 不会假设 live MCP 编辑已经被自动刷盘。
 
 Da Vinci 不把 headless interactive `save()` 当作权威持久化真相。
 
-正式持久化步骤是：
+主路径持久化步骤是：
 
-1. 读取 MCP 可读的 node snapshot
-2. 读取 MCP 可读的 variable snapshot
-3. 写项目内 `.pen`
-4. reopen 校验
-5. 比较 live snapshot hash 和 persisted snapshot hash
+1. 执行 `da-vinci save-current-design --project <project-path>`
+2. 明确读取结果包：`saved` / `blocked` / `unavailable`
+3. 只有 `saved` 才表示持久化成功
+4. `blocked` 表示保存时的来源/锁/载荷契约失败
+5. `unavailable` 表示 MCP bridge 或 runtime 抓取不可达，不能当成“已保存”
 
 相关命令：
 
-- `da-vinci write-pen`
-- `da-vinci check-pen-sync`
+- 高层主路径：`da-vinci save-current-design`
+- 底层回退路径：`da-vinci pencil-session persist`、`da-vinci write-pen`、`da-vinci check-pen-sync`
+
+MVP 安全保证仅覆盖“来源路径收敛”：registered `.pen`、session `penPath`、active editor path 必须收敛到同一文件。
+在 MCP 暴露稳定 window/editor 标识前，精确窗口实例绑定仍是非目标。
 
 `da-vinci snapshot-pen` 只用于 disk-to-disk，不是 live 编辑持久化路径。
 
@@ -253,7 +256,7 @@ Context Delta 相关审计期望都是告警级：
 1. `da-vinci pencil-session begin --project <project-path> --pen <path>`
 2. 如果存在外部/次要 `.pen`，在编辑前先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若分叉，先把优先来源同步回 `<project-pen>`
 3. Pencil MCP 编辑
-4. `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <nodes.json> --variables-file <vars.json> --version <version>`
+4. `da-vinci save-current-design --project <project-path>`
 5. screenshot review + layout hygiene
 6. design checkpoint
 7. 如果配置了，就执行 design-supervisor review
@@ -280,13 +283,13 @@ flowchart TD
     K -- 否 --> F
     K -- 是 --> L{是否配置了 design-supervisor review?}
     L -- 是 --> M[执行 design-supervisor review，结合 screenshots 与 theme inputs]
-    L -- 否 --> N[pencil-session persist 把 live MCP 快照写回 .pen]
+    L -- 否 --> N[save-current-design 把绑定的 live 快照写回 .pen]
     M --> O{是否要求 Supervisor Review?}
     O -- 否 --> N
     O -- 是 --> P{review 为 PASS 或已接受 WARN?}
     P -- 否 --> F
     P -- 是 --> N
-    N --> Q[check-pen-sync 校验 live hash 与 persisted hash 一致]
+    N --> Q[save-current-design 返回 saved 或终态 blocked/unavailable]
     Q --> R{design-source checkpoint 和 runtime gate 通过?}
     R -- 否 --> F
     R -- 是 --> S{是否还要继续设计?}

package/docs/zh-CN/prompt-entrypoints.md

@@ -86,6 +86,8 @@
 
 默认不要把这个流程改成 `build`。
 
+如果真正的阻力变成“命令太多记不住”，就启动 `da-vinci tui`，直接在终端 UI 里按阶段选择命令，而不是手动记每个 CLI surface。
+
 `build` 仍然有效，但它更适合已经明确进入实现阶段的高级直接调用。
 
 状态规则：

package/docs/zh-CN/prompt-presets/README.md

@@ -21,7 +21,7 @@
 4. 两者一起放进工作流设置
 5. 只有在项目存在特殊真相源或平台约束时，再继续收紧提示词
 6. 如果 Pencil MCP 可用，优先使用已经明确要求 MCP runtime gate 和 completion audit 的那版 redesign 提示词
-7. 如果项目要在自治运行里把 `.pen` 真正持久化到本地，必须使用要求 `da-vinci pencil-session begin / persist / end` 的提示词；只有 wrapper 确实不可用时再退回 `ensure-pen + write-pen + check-pen-sync`
+7. 如果项目要在自治运行里把 `.pen` 真正持久化到本地，必须使用要求 `da-vinci pencil-session begin / save-current-design / end` 的提示词；并明确区分 `saved` / `blocked` / `unavailable`，只有高层保存不可用时才回退到底层 payload 持久化链路
 
 可用模板：
 

package/docs/zh-CN/prompt-presets/desktop-app.md

@@ -120,7 +120,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
-在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，必须执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`。只有 session wrapper 不可用时，才退回 `ensure-pen + write-pen + check-pen-sync` 这条底层链路。
+在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接返回 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 这条底层链路。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果 `DA-VINCI.md` 配置了 `Design-supervisor reviewers`，就在 screenshot review、layout hygiene 和 design checkpoint 之后再做 `design-supervisor review`，输入要同时包含 screenshots、Pencil variables 和设计 thesis。若 `Require Supervisor Review: true`，那么缺失、`BLOCK`、或未被接受的 review 结果都要视为阻断。
@@ -156,7 +156,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout and whether it is primarily HTML-referenced, partially HTML-referenced, or inferred.
 
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 Run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Persist project-local Pencil files under .da-vinci/designs/.
@@ -190,7 +190,7 @@ $da-vinci use continue for this existing desktop-product redesign workflow.
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 选路先以当前工件和 checkpoint 真相为准，再把 Context Delta 作为辅助恢复信息；如果 Context Delta 与工件冲突，忽略冲突条目并记录冲突后继续。
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后再执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`；只有 session wrapper 不可用时，才退回 `write-pen + check-pen-sync` 这条底层链路。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable`；只有高层桥接返回 `unavailable` 时，才回退到底层 payload 持久化链路。
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 如果 Pencil MCP 可用，且这一轮继续做了新的 Pencil 写入，就重新运行 MCP runtime gate，并把最新结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。

package/docs/zh-CN/prompt-presets/mobile-app.md

@@ -126,7 +126,7 @@ Use only Pencil-supported properties; do not use web-only props like flex or mar
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
-在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，必须执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`。只有 session wrapper 不可用时，才退回 `ensure-pen + write-pen + check-pen-sync` 这条底层链路。
+在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接返回 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 这条底层链路。
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
@@ -164,7 +164,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout and whether it is primarily HTML-referenced, partially HTML-referenced, or inferred.
 
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 Run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Persist project-local Pencil files under .da-vinci/designs/.
@@ -198,7 +198,7 @@ $da-vinci use continue for this existing mobile-app redesign workflow.
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 选路先以当前工件和 checkpoint 真相为准，再把 Context Delta 作为辅助恢复信息；如果 Context Delta 与工件冲突，忽略冲突条目并记录冲突后继续。
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后再执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`；只有 session wrapper 不可用时，才退回 `write-pen + check-pen-sync` 这条底层链路。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable`；只有高层桥接返回 `unavailable` 时，才回退到底层 payload 持久化链路。
 If the redesign is complex, keep the anchor-first flow until the design checkpoint passes.
 如果 Pencil MCP 可用，且这一轮继续做了新的 Pencil 写入，就重新运行 MCP runtime gate，并把最新结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。

package/docs/zh-CN/prompt-presets/tablet-app.md

@@ -120,7 +120,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
-在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，必须执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`。只有 session wrapper 不可用时，才退回 `ensure-pen + write-pen + check-pen-sync` 这条底层链路。
+在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接返回 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 这条底层链路。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果 `DA-VINCI.md` 配置了 `Design-supervisor reviewers`，就在 screenshot review、layout hygiene 和 design checkpoint 之后再做 `design-supervisor review`，输入要同时包含 screenshots、Pencil variables 和设计 thesis。若 `Require Supervisor Review: true`，那么缺失、`BLOCK`、或未被接受的 review 结果都要视为阻断。
@@ -156,7 +156,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout and whether it is primarily HTML-referenced, partially HTML-referenced, or inferred.
 
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 Run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Persist project-local Pencil files under .da-vinci/designs/.
@@ -190,7 +190,7 @@ $da-vinci use continue for this existing tablet-product redesign workflow.
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 选路先以当前工件和 checkpoint 真相为准，再把 Context Delta 作为辅助恢复信息；如果 Context Delta 与工件冲突，忽略冲突条目并记录冲突后继续。
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后再执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`；只有 session wrapper 不可用时，才退回 `write-pen + check-pen-sync` 这条底层链路。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable`；只有高层桥接返回 `unavailable` 时，才回退到底层 payload 持久化链路。
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 如果 Pencil MCP 可用，且这一轮继续做了新的 Pencil 写入，就重新运行 MCP runtime gate，并把最新结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。

package/docs/zh-CN/prompt-presets/web-app.md

@@ -121,7 +121,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass。
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
-在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，必须执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`。只有 session wrapper 不可用时，才退回 `ensure-pen + write-pen + check-pen-sync` 这条底层链路。
+在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`；发生实质性 live edit 后，优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接返回 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 这条底层链路。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果 `DA-VINCI.md` 配置了 `Design-supervisor reviewers`，就在 screenshot review、layout hygiene 和 design checkpoint 之后再做 `design-supervisor review`，输入要同时包含 screenshots、Pencil variables 和设计 thesis。若 `Require Supervisor Review: true`，那么缺失、`BLOCK`、或未被接受的 review 结果都要视为阻断。
@@ -157,7 +157,7 @@ Design 1-3 anchor surfaces first, review screenshots, then expand.
 For each anchor surface, explain how the new composition differs structurally from the current layout and whether it is primarily HTML-referenced, partially HTML-referenced, or inferred.
 
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
-Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits.
+Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes.
 Run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete` or `workflow complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Persist project-local Pencil files under .da-vinci/designs/.
@@ -191,7 +191,7 @@ $da-vinci use continue for this existing web-product redesign workflow.
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 选路先以当前工件和 checkpoint 真相为准，再把 Context Delta 作为辅助恢复信息；如果 Context Delta 与工件冲突，忽略冲突条目并记录冲突后继续。
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后再执行 `da-vinci pencil-session persist --project <project-path> --pen <path> ...`；只有 session wrapper 不可用时，才退回 `write-pen + check-pen-sync` 这条底层链路。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。如果继续这一轮会做 Pencil 编辑，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`。必须区分 `saved`、`blocked`、`unavailable`；只有高层桥接返回 `unavailable` 时，才回退到底层 payload 持久化链路。
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 如果 Pencil MCP 可用，且这一轮继续做了新的 Pencil 写入，就重新运行 MCP runtime gate，并把最新结果记录到 `pencil-design.md`。
 在声明 `design complete` 或 `workflow complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。

package/docs/zh-CN/skill-usage.md

@@ -0,0 +1,224 @@
+# Skill 使用说明
+
+这份文档面向真正操作 Da Vinci 的人，而不是底层命令参考。
+
+重点讲四件事：
+
+- 第一次怎么进入 Da Vinci 工作流
+- 需求、设计、任务、实现几段之间怎么衔接
+- 中途退出后下次怎么安全恢复
+- 如果不想记太多命令，怎么用 TUI
+
+## 核心规则
+
+Da Vinci 应该根据工件真相恢复，而不是根据聊天记忆恢复。
+
+也就是说：
+
+- `spec.md` 以及相关需求工件是行为真相
+- 项目内 `.pen` 是设计真相
+- `tasks.md`、`verification.md` 和 execution signals 负责说明哪些东西已经实现、哪些还没实现
+
+## 第一次进入时怎么选入口
+
+这三个入口各有分工：
+
+- `intake`
+  - 适合项目复杂、mode 不明确、或有多个真相源的情况
+- `prompt`
+  - 适合 mode 已明确，只需要一条高质量起始提示词的情况
+- `continue`
+  - 适合仓库里已经有 `DA-VINCI.md` 或 `.da-vinci/`，需要恢复推进的情况
+
+对 Codex，最常见的起手式是：
+
+```text
+$da-vinci use intake for <project situation>
+$da-vinci use prompt for <known scenario>
+$da-vinci use continue for <existing workflow state>
+```
+
+默认建议：
+
+1. 第一次进入复杂项目时先用 `intake`
+2. 执行生成出来的主工作流提示词
+3. 如果中途停下，下次回来用 `continue`
+
+除非项目已经明显 implementation-ready，否则不要默认直接跳到 `build`。
+
+## 实际流程怎么走
+
+正常交付顺序通常是：
+
+1. 选择 mode
+2. 补 discovery 和 scope 工件
+3. 登记首选项目内 `.pen`
+4. 先做 1 到 3 个 anchor surfaces
+5. 让 live Pencil 会话和登记 `.pen` 收敛
+6. 写 `pencil-bindings.md`
+7. 生成或整理 `tasks.md`
+8. 实现
+9. 验证
+
+常见工件骨架一般是：
+
+- `DA-VINCI.md`
+- `.da-vinci/design-registry.md`
+- `.da-vinci/page-map.md`
+- `.da-vinci/changes/<change-id>/proposal.md`
+- `.da-vinci/changes/<change-id>/specs/*/spec.md`
+- `.da-vinci/changes/<change-id>/design.md`
+- `.da-vinci/changes/<change-id>/pencil-design.md`
+- `.da-vinci/changes/<change-id>/pencil-bindings.md`
+- `.da-vinci/changes/<change-id>/tasks.md`
+- `.da-vinci/changes/<change-id>/verification.md`
+
+## 进入实现前怎么衔接
+
+当设计大体完成，接下来准备实现时，建议按这个顺序看：
+
+- `da-vinci workflow-status`
+  - 先确认当前阶段和 blocker
+- `da-vinci next-step`
+  - 再确认下一步到底应该是 `design`、`tasks` 还是 `build`
+- `da-vinci lint-spec`
+  - 当运行时 spec 质量还不够确定时使用
+- `da-vinci scope-check`
+  - 当规划工件之间页面/状态传播关系还不清楚时使用
+
+如果你已经在项目根目录里，`--project` 通常可以省略，因为 CLI 默认会回退到当前目录。
+
+例如：
+
+```bash
+da-vinci workflow-status
+da-vinci next-step
+da-vinci lint-spec
+da-vinci scope-check
+```
+
+## 中途退出后，下次怎么恢复
+
+最稳妥的恢复顺序是：
+
+1. `da-vinci workflow-status [--change <id>] --json`
+2. `da-vinci next-step [--change <id>]`
+3. 如果 spec 质量不确定，跑 `da-vinci lint-spec`
+4. 如果规划传播关系不确定，跑 `da-vinci scope-check`
+5. 如果 planning 工件相对上次稳定状态有变化，跑 `da-vinci generate-sidecars` 和 `da-vinci diff-spec`
+6. 在终态前，跑 `da-vinci verify-bindings` 和 `da-vinci verify-coverage`
+
+恢复时应该遵循工件，而不是旧聊天上下文：
+
+- 如果设计工件已经有了，但 `tasks.md` 还没有，下一步应该回到 `tasks`
+- 如果 `tasks.md` 已存在，但设计 gate 还没过，不要直接进 `build`
+- 只有实现就绪度已经明确时，才把 `build` 当主恢复路径
+
+## `change-id` 到底是什么
+
+`change-id` 就是 `.da-vinci/changes/<change-id>/` 这个目录名。
+
+实际使用规则：
+
+- 如果项目里只有一个非空 change 目录，多数工作流命令都能自动推断
+- 如果项目里有多个非空 change 目录，就显式传 `--change <id>`
+- 尽量一条分支只维护一个 active change，这样续跑成本最低
+
+如果你忘了当前活跃 change 是哪个，先跑 `da-vinci workflow-status`。在多 change 场景下，它会告诉你可用的 ids，还会给一个“仅供参考”的最新推断值。
+
+## TUI 快速上手
+
+如果真正的痛点是不想记那么多命令面，就直接用终端 TUI。
+
+启动方式：
+
+```bash
+da-vinci tui
+da-vinci-tui
+```
+
+如果没有全局安装，也可以直接用 `npx`：
+
+```bash
+npx -p @xenonbyte/da-vinci-workflow da-vinci tui
+npx -p @xenonbyte/da-vinci-workflow da-vinci-tui
+```
+
+TUI 提供这些能力：
+
+- 首屏按场景组织：`安装与卸载`、`当前状态`、`切换工作项`、`设计操作`、`实施前检查`、`验收前检查`、`设置`
+- 常用链路直接做成组合入口（续跑、实施前检查、验收前检查）
+- `设计操作` 聚焦实用设计操作（`保存当前设计稿`、`同步图标库`、`Visual Assist 预设`）
+- `安装与卸载` 提供三个动作：`状态`（查看 `da-vinci status`）、`安装`（一键安装所有支持平台）、`卸载`（一键卸载所有支持平台）
+- 界面中英双语，但 Visual Assist 输出始终使用英文权威源
+- 顶部只保留最小上下文（项目 + change）
+- `设置` 仅保留 `语言` 和 `日志`
+- `设置 > 日志` 提供项目内每日诊断日志（`.da-vinci/logs/YYYY-MM-DD.ndjson`）
+
+### TUI 场景图
+
+```mermaid
+flowchart TD
+  A[启动 da-vinci tui] --> B[设置 project 和 change 上下文]
+  B --> C[安装与卸载<br/>状态 + 一键安装/卸载全部平台]
+  B --> D[当前状态<br/>workflow-status + next-step 总结]
+  B --> E[切换工作项<br/>选择已有 change]
+  B --> F[设计操作<br/>图标同步 + Visual Assist 预设]
+  B --> G[实施前检查<br/>实现前就绪度检查]
+  B --> H[验收前检查<br/>verify-* 链路]
+  B --> I[设置<br/>语言 + 日志]
+```
+
+你可以把它理解成这四条最实用的规则：
+
+- 先选“当前时机”对应的场景
+- 优先用场景入口完成常用检查
+- 只要中途暂停或路由不清晰，就进入“当前状态”
+- 只有“验收前检查”通过，才进入终态
+
+Visual Assist 预设映射（`设计操作 > Visual Assist 预设`）：
+
+- `Masterpiece` => `required reviewer signoff`
+- `High Quality` => `advisory reviewer`
+- `Normal` => `adapter-only`
+
+Visual Assist 受控写入规则：
+
+- 先选平台，再从 3 档质量中选择（对应 Variant 1/2/3）
+- 内容来自 `docs/visual-assist-presets/` 的英文权威源
+- 只替换项目根 `DA-VINCI.md` 的 `## Visual Assist`
+- 保留无关章节，避免重复 `## Visual Assist`
+
+主要按键：
+
+- `Up/Down` 或 `j/k`：移动选中项
+- `Enter` 或 `r`：进入当前场景/动作
+- `u/d`：长内容按页上下翻
+- `g/G`：长内容跳到顶部/底部
+- `p`：修改项目路径上下文
+- `c`：修改或清空 change-id 上下文
+- `l`：切换中英文
+- `t`：主题识别不准时，手动切换主题模式
+- `s`：切换 `--strict`
+- `J`：切换 `--json`
+- `e`：切换 `--continue-on-error`
+- `?`：打开帮助
+- `Ctrl-C`：紧急退出
+
+推荐的 TUI 使用顺序：
+
+1. 在项目根目录启动 TUI
+2. 先选当前任务对应的场景
+3. 再确认顶部的 project path 和 change-id
+4. 优先执行场景入口（`切换工作项`、`实施前检查`、`安装与卸载`、`验收前检查`）；需要续跑判断时进入 `当前状态`
+5. 需要管理 Visual Assist 时，进入 `设计操作 > Visual Assist 预设`，完成“平台 + 质量”选择后自动写入
+6. 需要查看安装态时进入 `安装与卸载 > 状态`；需要安装/卸载时进入 `安装与卸载 > 安装/卸载` 一键执行全部平台
+7. 排查问题时到 `设置 > 日志` 查看/复制当天日志；日志只做诊断证据，不替代工件真相
+
+## 实用简化规则
+
+- 在项目根目录里，通常不需要写 `--project`
+- 只有一个 active change 时，通常也不需要写 `--change`
+- 每次暂停回来，默认先跑 `workflow-status` 和 `next-step`
+- 觉得命令太散时，用 TUI
+- 已经很清楚要跑哪条命令、而且在写脚本时，直接用 CLI 更快

package/docs/zh-CN/workflow-examples.md

@@ -110,17 +110,18 @@ $da-vinci use redesign-from-code to inventory the current app, identify current
 11. 如果同一个 anchor surface 连续两次回滚，就切到每批不超过 6 个操作的微批次，直到拿到干净的 schema-safe pass
 12. 如果这一轮开始时还没有登记的项目内 `.pen`，必须先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，先 seed 登记路径并拿到全局锁，再开始第一次 Pencil 编辑
 13. 如果存在外部或历史 `.pen` 备份，在新一轮写入前先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若 hash 不一致，先把选中的优先来源同步回 `<project-pen>`
-14. 如果项目里原本已有登记的 `.pen`，继续设计时也必须先通过 `da-vinci pencil-session begin --project <project-path> --pen <path>` reopen 它；发生了实质性 live edit 后，再通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
-15. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
-16. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
-17. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
-18. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
-19. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
-20. 在 broad expansion 前，先把 screenshot review 的 `PASS` / `WARN` / `BLOCK`、问题列表和回改结果记清楚
-21. 绑定路由和 Pencil 页面
-22. 生成和 redesign slice 对齐的任务
-23. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
-24. 只有在 completion gate 最终能通过时，才进入实现和验证
+14. 如果项目里原本已有登记的 `.pen`，继续设计时也必须先通过 `da-vinci pencil-session begin --project <project-path> --pen <path>` reopen 它；发生实质性 live edit 后，优先执行 `da-vinci save-current-design --project <project-path>`
+15. 必须区分 `saved` / `blocked` / `unavailable`，只有 `saved` 才代表保存成功；`unavailable` 时才能回退到底层 payload 持久化链路
+16. 在第一次成功写入 Pencil 后，立即验证登记的项目内 `.pen` 路径已经成为 shell 可见文件
+17. 紧接着运行 `da-vinci audit --mode integrity <project-path>`
+18. 如果 Pencil MCP 可用，先运行 MCP runtime gate，并把结果记录到 `pencil-design.md`
+19. 运行 `design-source checkpoint`，确认登记的项目内 `.pen` 路径、当前 Pencil 设计源和 shell 可见文件是一致的
+20. 截图导出只放到 `.da-vinci/changes/<change-id>/exports/`，绝不能写进 `.da-vinci/designs/`
+21. 在 broad expansion 前，先把 screenshot review 的 `PASS` / `WARN` / `BLOCK`、问题列表和回改结果记清楚
+22. 绑定路由和 Pencil 页面
+23. 生成和 redesign slice 对齐的任务
+24. 在任何终态完成声明之前，先运行 `da-vinci audit --mode completion --change <change-id> <project-path>`
+25. 只有在 completion gate 最终能通过时，才进入实现和验证
 
 ### 复杂 Android 页面示例
 
@@ -145,7 +146,8 @@ If the same anchor surface rolls back twice, switch to micro-batches of 6 or few
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
 在第一次 Pencil 编辑前，必须执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，这样会先 seed 登记好的 `.pen` 并持有全局 Pencil 锁。
 如果存在外部或历史 `.pen`，先运行 `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>`；若 hash 分叉，先确认来源优先级并把选中的来源同步回 `<project-pen>` 再继续。
-如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 live MCP 快照重新覆盖写回同一路径。
+如果项目里原本已有登记的 `.pen`，继续设计时先打开它，但实质性 live edit 后优先通过 `da-vinci save-current-design --project <project-path>` 保存。
+必须区分 `saved` / `blocked` / `unavailable`；只有 `saved` 才是保存成功，`unavailable` 才能触发底层回退。
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 在第一次成功写入 Pencil 后、继续大范围扩展前，先运行 `da-vinci audit --mode integrity <project-path>`。
 Keep `.da-vinci/designs/` reserved for `.pen` files only.
@@ -218,7 +220,7 @@ If frontend-skill is available, use it as the primary visual adapter.
 If it is unavailable, fall back to native Da Vinci design rules and continue.
 Persist project-local Pencil files under .da-vinci/designs/.
 如果当前还没有登记的项目内 `.pen`，先在这里 seed 一个登记好的 `.pen`，再开始第一次 Pencil 编辑，并把后续 live 编辑持续绑定到这个路径。
-如果项目里原本已有 `.pen`，继续设计后要把当前 MCP 快照覆盖写回同一路径。
+如果项目里原本已有 `.pen`，继续设计后优先执行 `da-vinci save-current-design --project <project-path>` 持久化；只有高层保存返回 `unavailable` 时才回退到底层 payload 持久化。
 ```
 
 ## 图标库辅助示例

package/docs/zh-CN/workflow-overview.md

@@ -16,6 +16,7 @@
 如果你想看逐个 `dv:` 命令的职责、下一步推荐和 `verify` 回退规则，请看 [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/dv-command-reference.md)。
 如果你想看约束文件总览（哪些字段是硬门禁、哪些是指导项），请看 [constraint-files.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/constraint-files.md)。
 如果你想看 sidecar、enforcement、persisted-state 回退和 scaffold 约束，请看 [execution-chain-migration.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/execution-chain-migration.md)。
+如果你想看更偏操作手册的说明，比如第一次怎么进、暂停后怎么续跑、TUI 怎么用，请看 [skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/skill-usage.md)。
 
 ## 核心契约
 
@@ -158,6 +159,7 @@ anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 
 - `design-source checkpoint`
 - 如果启用了 Pencil MCP，则跑 `MCP runtime gate`
+- 发生实质性 live edit 后执行 `da-vinci save-current-design --project <project-path>`（高层绑定源保存路径）
 - 工作中期跑 `da-vinci audit --mode integrity <project-path>`
 - 在现有 change 工件里记录 checkpoint 邻近的 `Context Delta`
 
@@ -167,6 +169,7 @@ anchor 通过后，再抽 shared primitives，然后再扩更多页面。
 - active editor 是正确的设计源
 - shell 上确实有 `.pen`
 - live snapshot 和 persisted snapshot 已同步
+- 高层保存结果被诚实处理（`saved` / `blocked` / `unavailable`）
 - 最近关键执行上下文可恢复，但不会替代工件真相的选路权
 
 ### 6. Mapping

package/examples/greenfield-spec-markupflow/.da-vinci/state/execution-signals/demo__lint-tasks.json

@@ -0,0 +1,16 @@
+{
+  "version": 1,
+  "surface": "lint-tasks",
+  "status": "WARN",
+  "advisory": true,
+  "strict": false,
+  "failures": [
+    "Missing `.da-vinci/` directory."
+  ],
+  "warnings": [],
+  "notes": [
+    "lint-tasks defaults to advisory mode; pass `--strict` to block on findings."
+  ],
+  "timestamp": "2026-03-31T16:22:40.193Z",
+  "changeId": "demo"
+}

package/lib/audit-parsers.js

@@ -244,18 +244,27 @@ function normalizeCheckpointLabel(value) {
 
 function parseCheckpointStatusMap(markdownText) {
   const section = getMarkdownSection(markdownText, "Checkpoint Status");
-  if (!section) {
-    return {};
+  const statuses = {};
+
+  if (section) {
+    const matches = section.matchAll(/(?:^|\n)\s*-\s*`?([^`:\n]+?)`?\s*:\s*(PASS|WARN|BLOCK)\b/gi);
+    for (const match of matches) {
+      const label = normalizeCheckpointLabel(match[1]);
+      if (!label) {
+        continue;
+      }
+      statuses[label] = String(match[2]).toUpperCase();
+    }
   }
 
-  const statuses = {};
-  const matches = section.matchAll(/(?:^|\n)\s*-\s*`?([^`:\n]+?)`?\s*:\s*(PASS|WARN|BLOCK)\b/gi);
-  for (const match of matches) {
-    const label = normalizeCheckpointLabel(match[1]);
-    if (!label) {
-      continue;
+  const runtimeGateSection = getMarkdownSection(markdownText, "MCP Runtime Gate");
+  if (runtimeGateSection) {
+    const runtimeGateMatch = String(runtimeGateSection).match(
+      /(?:^|\n)\s*-\s*(?:Final runtime gate status|Status|状态)\s*:\s*`?(PASS|WARN|BLOCK)`?\b/i
+    );
+    if (runtimeGateMatch) {
+      statuses[normalizeCheckpointLabel("mcp runtime gate")] = String(runtimeGateMatch[1]).toUpperCase();
     }
-    statuses[label] = String(match[2]).toUpperCase();
   }
 
   return statuses;

package/lib/audit.js

@@ -8,7 +8,8 @@ const {
   assertPenDocumentShape
 } = require("./pen-persistence");
 const { getSessionStatePath, readSessionState } = require("./pencil-session");
-const { isPathInside, listFilesRecursiveSafe } = require("./fs-safety");
+const { listFilesRecursiveSafe } = require("./fs-safety");
+const { collectRegisteredPenPaths } = require("./design-source-registry");
 const { pathExists, readTextIfExists } = require("./utils");
 const { runModuleExportInWorker } = require("./async-offload");
 const { readExecutionSignals, summarizeSignalsBySurface } = require("./execution-signals");
@@ -69,30 +70,6 @@ function relativeTo(projectRoot, targetPath) {
   return path.relative(projectRoot, targetPath) || ".";
 }
 
-function collectRegisteredPenPaths(projectRoot, designRegistryPath) {
-  const registryText = readTextIfExists(designRegistryPath);
-  const matches = registryText.match(/\.da-vinci\/designs\/[^\s`]+\.pen/g) || [];
-  const validPaths = [];
-  const escapedPaths = [];
-
-  for (const relativePath of [...new Set(matches)]) {
-    const resolvedPath = path.resolve(projectRoot, relativePath);
-    if (!isPathInside(projectRoot, resolvedPath)) {
-      escapedPaths.push({
-        relativePath,
-        resolvedPath
-      });
-      continue;
-    }
-    validPaths.push(resolvedPath);
-  }
-
-  return {
-    validPaths,
-    escapedPaths
-  };
-}
-
 function getNonEmptyChangeDirs(changesDir) {
   return listChildDirs(changesDir).filter((changeDir) => {
     const scan = listFilesRecursive(changeDir, CHANGE_SCAN_LIMITS);
@@ -368,7 +345,7 @@ function auditProject(projectPathInput, options = {}) {
   const {
     validPaths: registeredPenPaths,
     escapedPaths: escapedRegisteredPenPaths
-  } = collectRegisteredPenPaths(projectRoot, designRegistryPath);
+  } = collectRegisteredPenPaths(projectRoot, readTextIfExists(designRegistryPath));
   for (const escapedPath of escapedRegisteredPenPaths) {
     const message =
       `Registered design source escapes project root and will be ignored: ${escapedPath.relativePath} ` +