@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.3

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

@@ -146,67 +146,74 @@ npx -p @xenonbyte/da-vinci-workflow da-vinci-tui
 
 TUI 提供这些能力：
 
-- 按工作流阶段对命令分组
-- 中英文双语界面说明
-- 顶部显示当前项目路径和 change-id 上下文
-- 执行前可先看命令预览
-- 一键切换 `--strict`、`--json`、`--continue-on-error`
-- 对 `<pen-path>` 这类还没补具体路径的命令，支持先编辑预览再执行
+- 首屏按场景组织：`安装与卸载`、`当前状态`、`切换工作项`、`设计操作`、`实施前检查`、`验收前检查`、`设置`
+- 常用链路直接做成组合入口（续跑、实施前检查、验收前检查）
+- `设计操作` 聚焦实用设计操作（`保存当前设计稿`、`同步图标库`、`Visual Assist 预设`）
+- `安装与卸载` 提供三个动作：`状态`（查看 `da-vinci status`）、`安装`（一键安装所有支持平台）、`卸载`（一键卸载所有支持平台）
+- 界面中英双语，但 Visual Assist 输出始终使用英文权威源
+- 顶部只保留最小上下文（项目 + change）
+- `设置` 仅保留 `语言` 和 `日志`
+- `设置 > 日志` 提供项目内每日诊断日志（`.da-vinci/logs/YYYY-MM-DD.ndjson`）
 
-### TUI 阶段图
+### TUI 场景图
 
 ```mermaid
 flowchart TD
-  A[启动 da-vinci tui] --> B[设置 project path 和 change-id 上下文]
-  B --> C[选路与续跑<br/>workflow-status / next-step]
-  C --> D{当前处于哪个阶段?}
-
-  D --> E[规划与漂移检查<br/>lint-spec / scope-check / lint-tasks / lint-bindings / generate-sidecars / diff-spec / scaffold]
-  D --> F[视觉与审查<br/>icon-sync / icon-search / supervisor-review]
-  D --> G[Pen 文件与同步<br/>preflight-pencil / ensure-pen / write-pen / check-pen-sync / check-pen-baseline / sync-pen-source / snapshot-pen]
-  D --> H[Pencil 会话<br/>pencil-lock * / pencil-session begin|persist|end|status]
-  D --> I[验证与完成<br/>verify-bindings / verify-implementation / verify-structure / verify-coverage / audit]
-  D --> J[初始化与工具<br/>install / uninstall / status / validate-assets / bootstrap-project]
-
-  E --> I
-  F --> G
-  G --> H
-  H --> E
-  I --> K{可以收尾了吗?}
-  K -->|还不行| C
-  K -->|可以| L[跑 completion audit 并做终态声明]
+  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/>语言 + 日志]
 ```
 
 你可以把它理解成这四条最实用的规则：
 
-- 先从“选路与续跑”开始
-- 再进入当前 blocker 所在的阶段
-- 只要中途暂停，或者工件发生了实质变化，就回到“选路与续跑”
-- 只有验证链和 completion audit 都通过了，才进入终态
+- 先选“当前时机”对应的场景
+- 优先用场景入口完成常用检查
+- 只要中途暂停或路由不清晰，就进入“当前状态”
+- 只有“验收前检查”通过，才进入终态
+
+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`：执行当前命令
-- `h`：查看当前命令参数
-- `m`：先编辑预览命令
+- `Enter` 或 `r`：进入当前场景/动作
+- `u/d`：长内容按页上下翻
+- `g/G`：长内容跳到顶部/底部
 - `p`：修改项目路径上下文
 - `c`：修改或清空 change-id 上下文
 - `l`：切换中英文
+- `t`：主题识别不准时，手动切换主题模式
 - `s`：切换 `--strict`
 - `J`：切换 `--json`
 - `e`：切换 `--continue-on-error`
 - `?`：打开帮助
-- `q`：退出
+- `Ctrl-C`：紧急退出
 
 推荐的 TUI 使用顺序：
 
 1. 在项目根目录启动 TUI
-2. 先确认顶部的 project path 和 change-id
-3. 先跑 `workflow-status`
-4. 再跑 `next-step`
-5. 根据情况进入 `lint-spec`、`scope-check`、`tasks`、`verify-*`
-6. 如果是 Pencil 相关特殊命令，按 `m` 先把剩余占位符补全后再执行
+2. 先选当前任务对应的场景
+3. 再确认顶部的 project path 和 change-id
+4. 优先执行场景入口（`切换工作项`、`实施前检查`、`安装与卸载`、`验收前检查`）；需要续跑判断时进入 `当前状态`
+5. 需要管理 Visual Assist 时，进入 `设计操作 > Visual Assist 预设`，完成“平台 + 质量”选择后自动写入
+6. 需要查看安装态时进入 `安装与卸载 > 状态`；需要安装/卸载时进入 `安装与卸载 > 安装/卸载` 一键执行全部平台
+7. 排查问题时到 `设置 > 日志` 查看/复制当天日志；日志只做诊断证据，不替代工件真相
 
 ## 实用简化规则
 

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

@@ -159,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`
 
@@ -168,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} ` +

package/lib/cli.js

@@ -32,6 +32,11 @@ const {
   endPencilSession,
   getPencilSessionStatus
 } = require("./pencil-session");
+const {
+  SAVE_STATUS,
+  saveCurrentDesign,
+  formatSaveCurrentDesignReport
+} = require("./save-current-design");
 const {
   searchIconLibrary,
   formatIconSearchReport
@@ -83,6 +88,7 @@ const OPTION_FLAGS_WITH_VALUES = new Set([
   "--home",
   "--platform",
   "--lang",
+  "--tui-width",
   "--project",
   "--mode",
   "--change",
@@ -113,6 +119,7 @@ const OPTION_FLAGS_WITH_VALUES = new Set([
   "--from",
   "--to",
   "--pen",
+  "--pencil-bin",
   "--nodes-file",
   "--variables-file",
   "--version",
@@ -123,6 +130,7 @@ const OPTION_FLAGS_WITH_VALUES = new Set([
 const HELP_OPTION_SPECS = [
   { flag: "--platform <value>", description: "codex, claude, gemini, or all" },
   { flag: "--lang <value>", description: "ui language for `da-vinci tui`: en or zh" },
+  { flag: "--tui-width <cols>", description: "fixed layout width (columns) for `da-vinci tui`" },
   { flag: "--home <path>", description: "override HOME for installation targets" },
   { flag: "--project <path>", description: "override project path for audit" },
   {
@@ -188,12 +196,15 @@ const HELP_OPTION_SPECS = [
     flag: "--strict",
     description: "enable strict failure mode for commands that support advisory defaults (for example icon-sync, lint-spec)"
   },
+  { flag: "--alt-screen", description: "enable alternate terminal screen buffer for `da-vinci tui`" },
+  { flag: "--no-alt-screen", description: "disable alternate terminal screen buffer for `da-vinci tui`" },
   {
     flag: "--continue-on-error",
     description: "print BLOCK/FAIL command results without throwing process errors"
   },
   { flag: "--json", description: "print structured JSON output when supported by the command" },
   { flag: "--pen <path>", description: "registered .pen path for sync checks" },
+  { flag: "--pencil-bin <path>", description: "override Pencil executable for interactive capture/verify flows" },
   {
     flag: "--from <path>",
     description: "source path for sync-pen-source, or baseline sidecars directory for diff-spec"
@@ -475,7 +486,7 @@ function printHelp() {
       "  da-vinci install --platform codex,claude,gemini",
       "  da-vinci uninstall --platform codex,claude,gemini",
       "  da-vinci status",
-      "  da-vinci tui [--project <path>] [--change <id>] [--lang en|zh] [--strict] [--json] [--continue-on-error]",
+      "  da-vinci tui [--project <path>] [--change <id>] [--lang en|zh] [--strict] [--json] [--continue-on-error] [--tui-width <cols>] [--alt-screen|--no-alt-screen]",
       "  da-vinci workflow-status [--project <path>] [--change <id>] [--json]",
       "  da-vinci next-step [--project <path>] [--change <id>] [--json]",
       "  da-vinci lint-spec [--project <path>] [--change <id>] [--strict] [--json]",
@@ -502,6 +513,7 @@ function printHelp() {
       "  da-vinci check-pen-baseline --pen <path> --baseline <path>[,<path>...] [--baseline <path>] [--prefer-source <path>]",
       "  da-vinci sync-pen-source --from <path> --to <path>",
       "  da-vinci snapshot-pen --input <path> --output <path>",
+      "  da-vinci save-current-design --project <path> [--json] [--continue-on-error]",
       "  da-vinci pencil-lock acquire --project <path>",
       "  da-vinci pencil-lock release --project <path>",
       "  da-vinci pencil-lock status",
@@ -945,6 +957,12 @@ async function runCli(argv) {
     const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
     const changeId = getOption(argv, "--change");
     const lang = getOption(argv, "--lang");
+    const tuiWidth = getOption(argv, "--tui-width");
+    const altScreen = argv.includes("--alt-screen")
+      ? true
+      : argv.includes("--no-alt-screen")
+        ? false
+        : undefined;
     if (argv.includes("--help") || argv.includes("-h")) {
       console.log(formatTuiHelp(lang));
       return;
@@ -953,6 +971,8 @@ async function runCli(argv) {
       projectPath,
       changeId,
       lang,
+      tuiWidth,
+      altScreen,
       strict: argv.includes("--strict"),
       jsonOutput: argv.includes("--json"),
       continueOnError
@@ -1425,6 +1445,35 @@ async function runCli(argv) {
     return;
   }
 
+  if (command === "save-current-design") {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const pencilBin = getOption(argv, "--pencil-bin");
+    const result = await saveCurrentDesign({
+      projectPath,
+      homeDir,
+      pencilBin,
+      allowLocalBridge: true
+    });
+    const useJson = argv.includes("--json");
+    const output = useJson
+      ? JSON.stringify(result, null, 2)
+      : formatSaveCurrentDesignReport(result);
+
+    if (
+      emitOrThrowOnStatus(
+        result.status,
+        [SAVE_STATUS.BLOCKED, SAVE_STATUS.UNAVAILABLE],
+        output,
+        continueOnError
+      )
+    ) {
+      return;
+    }
+
+    console.log(output);
+    return;
+  }
+
   if (command === "pencil-lock") {
     handlePencilLockCommand(argv, homeDir);
     return;

package/lib/design-source-registry.js

@@ -0,0 +1,146 @@
+const path = require("path");
+const { isPathInside } = require("./fs-safety");
+
+const REGISTERED_PEN_PATTERN = /\.da-vinci\/designs\/[^\s`]+\.pen/g;
+
+function normalizeProjectRoot(projectRoot) {
+  return path.resolve(projectRoot || process.cwd());
+}
+
+function collectRegisteredPenReferences(registryText) {
+  const matches = String(registryText || "").match(REGISTERED_PEN_PATTERN) || [];
+  const seen = new Set();
+  const unique = [];
+
+  for (const match of matches) {
+    const normalized = String(match || "").trim();
+    if (!normalized || seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    unique.push(normalized);
+  }
+
+  return unique;
+}
+
+function normalizeBoundPenPath(projectRoot, penPath, options = {}) {
+  const root = normalizeProjectRoot(projectRoot);
+  const raw = typeof penPath === "string" ? penPath.trim() : "";
+
+  if (!raw) {
+    return {
+      ok: false,
+      code: options.missingCode || "missing_path",
+      input: raw,
+      resolvedPath: ""
+    };
+  }
+
+  if (options.rejectNew && raw.toLowerCase() === "new") {
+    return {
+      ok: false,
+      code: options.newCode || "active_editor_new",
+      input: raw,
+      resolvedPath: ""
+    };
+  }
+
+  const resolvedPath = path.normalize(path.isAbsolute(raw) ? raw : path.resolve(root, raw));
+  if (!isPathInside(root, resolvedPath)) {
+    return {
+      ok: false,
+      code: options.outsideCode || "outside_project_root",
+      input: raw,
+      resolvedPath
+    };
+  }
+
+  if (options.requirePenExtension !== false && !/\.pen$/i.test(resolvedPath)) {
+    return {
+      ok: false,
+      code: options.extensionCode || "not_pen_path",
+      input: raw,
+      resolvedPath
+    };
+  }
+
+  return {
+    ok: true,
+    code: "ok",
+    input: raw,
+    resolvedPath
+  };
+}
+
+function normalizeRegisteredPenPath(projectRoot, penPath) {
+  return normalizeBoundPenPath(projectRoot, penPath, {
+    missingCode: "registered_pen_missing",
+    outsideCode: "registered_pen_outside_project_root",
+    extensionCode: "registered_pen_not_pen_path"
+  });
+}
+
+function normalizeSessionPenPath(projectRoot, penPath) {
+  return normalizeBoundPenPath(projectRoot, penPath, {
+    missingCode: "session_pen_missing",
+    outsideCode: "session_pen_outside_project_root",
+    extensionCode: "session_pen_not_pen_path"
+  });
+}
+
+function normalizeActiveEditorPath(projectRoot, activeEditorPath) {
+  return normalizeBoundPenPath(projectRoot, activeEditorPath, {
+    rejectNew: true,
+    missingCode: "active_editor_missing",
+    newCode: "active_editor_new",
+    outsideCode: "active_editor_outside_project_root",
+    extensionCode: "active_editor_not_pen_path"
+  });
+}
+
+function collectRegisteredPenPaths(projectRoot, registryText) {
+  const root = normalizeProjectRoot(projectRoot);
+  const references = collectRegisteredPenReferences(registryText);
+  const validPaths = [];
+  const escapedPaths = [];
+  const seenResolved = new Set();
+
+  for (const relativePath of references) {
+    const normalized = normalizeRegisteredPenPath(root, relativePath);
+    if (normalized.ok) {
+      if (!seenResolved.has(normalized.resolvedPath)) {
+        seenResolved.add(normalized.resolvedPath);
+        validPaths.push(normalized.resolvedPath);
+      }
+      continue;
+    }
+
+    if (normalized.code === "registered_pen_outside_project_root") {
+      escapedPaths.push({
+        relativePath,
+        resolvedPath: normalized.resolvedPath
+      });
+    }
+  }
+
+  return {
+    validPaths,
+    escapedPaths
+  };
+}
+
+function resolvePreferredRegisteredPenPath(projectRoot, registryText) {
+  const resolved = collectRegisteredPenPaths(projectRoot, registryText);
+  return resolved.validPaths[0] || "";
+}
+
+module.exports = {
+  collectRegisteredPenReferences,
+  normalizeBoundPenPath,
+  normalizeRegisteredPenPath,
+  normalizeSessionPenPath,
+  normalizeActiveEditorPath,
+  collectRegisteredPenPaths,
+  resolvePreferredRegisteredPenPath
+};