@xenonbyte/da-vinci-workflow 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v0.2.2 - 2026-03-31
+
+### Added
+- built-in terminal TUI surfaces via `da-vinci tui` and `da-vinci-tui`, with phase-grouped command discovery, bilingual labels, previewable execution, and project/change context controls
+- in-TUI command parameter help so operators can inspect supported flags, placeholders, and required inputs before editing a preview command
+- operator-facing English and Chinese workflow guides covering first-run routing, implementation handoff, pause/resume recovery, and TUI usage
+- TUI regression coverage plus package-content checks for the dedicated TUI bin and shipped `tui/` assets
+
+### Changed
+- README and Chinese companion docs now document the `0.2.2` TUI/operator release surface explicitly
+- TUI child commands now execute from the active project context selected in the header instead of always inheriting the original launch cwd
+
+### Fixed
+- `q` and `Ctrl-C` now fully terminate the TUI session instead of clearing the screen while leaving stdin resumed in the foreground
+- preview-command editing now treats unclosed quotes as a recoverable TUI error instead of crashing the process
+- the TUI JSON shortcut now uses `J`, preserving lowercase `j/k` for navigation without unreachable toggle branches
+
 ## v0.2.1 - 2026-03-31
 
 ### Added

package/README.md

@@ -28,18 +28,18 @@ This workflow is intended for:
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.2.1`
+- `@xenonbyte/da-vinci-workflow@0.2.2`
 
-Release highlights for `0.2.1`:
+Release highlights for `0.2.2`:
 
-- added the execution-chain workflow surfaces: `workflow-status`, `next-step`, `lint-spec`, `scope-check`, `lint-tasks`, `lint-bindings`, `generate-sidecars`, `verify-*`, `diff-spec`, and `scaffold`
-- introduced persisted workflow state plus execution-signal recording so route selection can reuse trusted snapshots while still honoring fresh verify and audit blockers
-- added planning sidecars, diffing, and scaffold generation from bindings to make planning drift and implementation coverage visible from the CLI
-- split CI into core regression, contracts, and workflow e2e lanes so the new workflow-state surfaces are exercised independently
-- expanded regression coverage for workflow-state derivation, persisted-state reuse, planning lints, sidecar generation, verify/scaffold, and audit execution-signal integration
-- fixed `generate-sidecars` so unresolved workflow/change selection returns `BLOCK` instead of a misleading `PASS`
-- fixed `verify-implementation` so test, fixture, and script files do not satisfy implementation coverage heuristics
-- refreshed release and command docs to document the new execution-chain surfaces in both English and Chinese
+- added the built-in terminal TUI via `da-vinci tui` and `da-vinci-tui`, with phase-grouped command discovery, bilingual labels, command previews, and project/change context management
+- added command-parameter help inside the TUI so operators can inspect supported flags and placeholder requirements without leaving the terminal
+- added operator-facing English and Chinese workflow guides that explain first-run routing, implementation handoff, pause/resume rules, and TUI usage
+- expanded release coverage with TUI-specific regression tests plus package-content checks for the dedicated TUI bin and shipped `tui/` assets
+- fixed TUI exit handling so `q` and `Ctrl-C` actually terminate the interactive session instead of leaving stdin resumed in the foreground
+- fixed preview-command editing so unclosed quotes are handled as a recoverable TUI error instead of crashing the process
+- fixed TUI JSON toggling by moving the shortcut to `J`, preserving `j/k` for navigation only
+- fixed TUI child-command execution so relative paths resolve from the active project context selected in the header
 
 ## Supported workflow modes
 
@@ -93,6 +93,17 @@ Route discipline:
 - contextual checkpoint deltas are auxiliary recovery notes only and must not override routing
 - if contextual deltas conflict with current artifacts, ignore them for routing and record the conflict
 
+## TUI Quick Start
+
+If the growing CLI surface is the main usability problem, use the built-in terminal UI instead of memorizing commands.
+
+- launch with `da-vinci tui` or `da-vinci-tui`
+- use `npx -p @xenonbyte/da-vinci-workflow da-vinci tui` when the package is not installed globally
+- the TUI groups commands by workflow phase, supports English and Chinese descriptions, and lets you launch the selected command after previewing it
+- `p` sets project path context, `c` sets change-id context, `l` toggles language, `m` edits the preview command, and `Enter` runs it
+
+Use [docs/skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/skill-usage.md) for the operator-facing workflow, resume rules, and TUI guidance.
+
 ## Visual Assist Quick Start
 
 Use `Visual Assist` when the project wants optional help from local UI-design skills such as `frontend-skill` or `ui-ux-pro-max`.

package/README.zh-CN.md

@@ -30,18 +30,18 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.2.1`
+- `@xenonbyte/da-vinci-workflow@0.2.2`
 
-`0.2.1` 版本重点：
+`0.2.2` 版本重点：
 
-- 新增 execution-chain CLI surface：`workflow-status`、`next-step`、`lint-spec`、`scope-check`、`lint-tasks`、`lint-bindings`、`generate-sidecars`、`verify-*`、`diff-spec`、`scaffold`
-- 新增持久化 workflow state 与 execution signal 记录，路由判断可以复用可信快照，同时继续尊重最新 verify / audit 阻塞结果
-- 新增 planning sidecar、diff 和基于 bindings 的 scaffold，方便直接从 CLI 看 planning drift 和实现覆盖
-- CI 现已拆成 core regression、contracts、workflow e2e 三条 lane，execution-chain 新流程会被独立回归
-- 回归测试新增覆盖 workflow-state 推导、persisted-state 复用、planning lint、sidecar 生成、verify/scaffold 与 audit execution-signal 集成
-- 修复 `generate-sidecars`：当 workflow / change 无法解析时，返回 `BLOCK`，不再误报 `PASS`
-- 修复 `verify-implementation`：测试文件、fixture 和脚本文件不再被当成真实实现覆盖证据
-- 中英文 README 与命令文档现已同步补充 execution-chain 新表面说明
+- 新增内置终端 TUI：可通过 `da-vinci tui` 和 `da-vinci-tui` 启动，按阶段分组浏览命令，支持中英文说明、命令预览以及 project/change 上下文维护
+- 新增 TUI 内的命令参数帮助，可以直接在终端里查看支持的 flag、占位符和必填参数
+- 新增中英文 operator 文档，专门说明第一次如何进入、实现前如何衔接、中途退出后怎么恢复，以及 TUI 怎么配合
+- 回归测试与打包校验现已覆盖 TUI 专项路径，包括独立 bin、`tui/` 目录资产和帮助输出
+- 修复 TUI 退出路径：`q` 和 `Ctrl-C` 现在会真正结束会话，不再把进程留在前台挂住
+- 修复预览命令编辑：未闭合引号现在会显示可恢复错误页，不再直接把 TUI 进程打崩
+- 修复 TUI 的 JSON 切换快捷键冲突：现在使用 `J` 切换 `--json`，`j/k` 只负责移动
+- 修复 TUI 子命令执行目录：相对路径现在会基于当前 header 里选中的项目上下文解析
 
 ## 支持的工作流模式
 
@@ -98,6 +98,17 @@ Da Vinci 当前支持五种模式：
 - Context Delta 只用于恢复上下文，不是阶段判定真相源
 - 如果 Context Delta 与当前工件冲突，应该忽略冲突条目并按工件真相继续
 
+## TUI 快速上手
+
+如果真正的痛点是 CLI 面太多、不想记命令，就直接用内置终端 TUI。
+
+- 用 `da-vinci tui` 或 `da-vinci-tui` 启动
+- 没有全局安装时，用 `npx -p @xenonbyte/da-vinci-workflow da-vinci tui`
+- TUI 会按工作流阶段对命令分组，支持中英文说明，并在执行前先给出命令预览
+- `p` 设置项目路径上下文，`c` 设置 change-id 上下文，`l` 切换语言，`m` 编辑预览命令，`Enter` 执行
+
+如果你想看“人到底怎么用这个 skill、暂停后怎么续跑、TUI 怎么配合”的完整说明，直接看 [docs/zh-CN/skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/zh-CN/skill-usage.md)。
+
 ## Visual Assist 快速上手
 
 当项目想借助本地 UI 设计 skill，例如 `frontend-skill` 或 `ui-ux-pro-max`，来提升设计质量时，就配置 `Visual Assist`。

package/bin/da-vinci-tui.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../lib/cli");
+
+runCli(["tui", ...process.argv.slice(2)]).catch((error) => {
+  console.error(error.message || String(error));
+  process.exit(1);
+});

package/docs/dv-command-reference.md

@@ -37,6 +37,10 @@ These helpers exist to select or resume the correct route. They are not substitu
 
 These commands do not replace route selection, but they support design execution quality:
 
+- `da-vinci tui [--project <path>] [--change <id>] [--lang en|zh]`
+  - opens a workflow-oriented terminal UI that groups commands by phase and lets you run them after previewing the generated CLI
+  - use `da-vinci-tui` as the dedicated bin alias, or `npx -p @xenonbyte/da-vinci-workflow da-vinci tui` without a global install
+  - useful when the command surface is harder to remember than the workflow itself
 - `da-vinci workflow-status --project <path> [--change <id>] [--json]`
   - derives the current workflow stage from artifact and checkpoint truth
   - reports blockers, warnings, handoff-gate state, and one primary route recommendation

package/docs/prompt-entrypoints.md

@@ -85,6 +85,8 @@ Use this default sequence:
 
 Do not default this sequence to `build`.
 
+If command recall becomes the main friction, launch `da-vinci tui` and use the grouped workflow surfaces from the terminal UI instead of memorizing each CLI surface manually.
+
 `build` is still valid, but it is an expert route for workflows that are already implementation-ready.
 
 State rule:

package/docs/skill-usage.md

@@ -0,0 +1,217 @@
+# Skill Usage Guide
+
+Use this document when you want the operator-facing workflow rather than the lower-level command reference.
+
+This guide focuses on:
+
+- how to enter the Da Vinci workflow the first time
+- how to move between requirement, design, task, and implementation phases
+- how to resume safely after pausing midway
+- how to use the TUI instead of memorizing many CLI surfaces
+
+## Core Rule
+
+Da Vinci should be resumed from artifact truth, not from chat memory.
+
+That means:
+
+- `spec.md` and related requirement artifacts stay the behavior truth
+- the project-local `.pen` stays the design truth
+- `tasks.md`, `verification.md`, and execution signals explain what has or has not been implemented yet
+
+## First Entry
+
+Use these entry helpers:
+
+- `intake`
+  - choose this when the project is complex, the mode is unclear, or there are multiple truth sources
+- `prompt`
+  - choose this when the mode is already known and you only need a good executable starting prompt
+- `continue`
+  - choose this when `DA-VINCI.md` or `.da-vinci/` artifacts already exist and you are resuming work
+
+For Codex, the usual first requests are:
+
+```text
+$da-vinci use intake for <project situation>
+$da-vinci use prompt for <known scenario>
+$da-vinci use continue for <existing workflow state>
+```
+
+Default recommendation:
+
+1. use `intake` on the first pass through a non-trivial project
+2. execute the generated main workflow prompt
+3. when work pauses, come back through `continue`
+
+Do not default directly to `build` unless the project is already implementation-ready.
+
+## Real Workflow
+
+The normal delivery flow is:
+
+1. choose the mode
+2. create or stabilize discovery and scope artifacts
+3. register the preferred project-local `.pen` source
+4. design 1 to 3 anchor surfaces first
+5. reconcile the live Pencil session with the registered `.pen`
+6. write `pencil-bindings.md`
+7. generate or refine `tasks.md`
+8. implement
+9. verify
+
+The artifact spine usually looks like this:
+
+- `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`
+
+## Before Implementation
+
+When design is mostly ready and implementation is next, use these checks:
+
+- `da-vinci workflow-status`
+  - confirm the active stage and blockers first
+- `da-vinci next-step`
+  - confirm whether the next move should still be `design`, `tasks`, or `build`
+- `da-vinci lint-spec`
+  - use this when runtime spec quality is still uncertain
+- `da-vinci scope-check`
+  - use this when page/state propagation across planning artifacts looks ambiguous
+
+If you are already inside the project root directory, `--project` is optional because the CLI falls back to `cwd`.
+
+Examples:
+
+```bash
+da-vinci workflow-status
+da-vinci next-step
+da-vinci lint-spec
+da-vinci scope-check
+```
+
+## After Pausing Midway
+
+The safest resume order is:
+
+1. `da-vinci workflow-status [--change <id>] --json`
+2. `da-vinci next-step [--change <id>]`
+3. if spec quality is unclear, run `da-vinci lint-spec`
+4. if planning propagation is unclear, run `da-vinci scope-check`
+5. if planning artifacts changed since the last stable snapshot, run `da-vinci generate-sidecars` and `da-vinci diff-spec`
+6. before terminal completion, run `da-vinci verify-bindings` and `da-vinci verify-coverage`
+
+Resume should follow the artifacts, not old conversation state:
+
+- if design artifacts exist but `tasks.md` does not, resume into `tasks`
+- if `tasks.md` exists but design gates are still unresolved, resume into design cleanup rather than `build`
+- only resume into `build` when implementation readiness is already clear
+
+## How `change-id` Works
+
+`change-id` is the directory name under `.da-vinci/changes/<change-id>/`.
+
+Practical rules:
+
+- if the project only has one non-empty change directory, most workflow commands can infer it automatically
+- if the project has multiple non-empty change directories, pass `--change <id>` explicitly
+- keep one active change per branch when possible to reduce routing friction
+
+Use `da-vinci workflow-status` when you forget which change is active. In multi-change cases it reports the available ids and the latest inferred one for context.
+
+## TUI Quick Start
+
+If remembering many command surfaces is the main friction, use the terminal UI instead of typing commands from memory.
+
+Launch it with either:
+
+```bash
+da-vinci tui
+da-vinci-tui
+```
+
+Or through `npx` without installing globally:
+
+```bash
+npx -p @xenonbyte/da-vinci-workflow da-vinci tui
+npx -p @xenonbyte/da-vinci-workflow da-vinci-tui
+```
+
+The TUI provides:
+
+- command grouping by workflow phase
+- English and Chinese UI descriptions
+- current project path and change-id context at the top
+- preview commands before execution
+- one-key toggles for `--strict`, `--json`, and `--continue-on-error`
+- placeholder-aware editing for commands that still need specific paths like `<pen-path>`
+
+### TUI Phase Map
+
+```mermaid
+flowchart TD
+  A[Launch da-vinci tui] --> B[Set project path and change-id context]
+  B --> C[Routing & Resume<br/>workflow-status / next-step]
+  C --> D{Which phase is active?}
+
+  D --> E[Planning & Drift<br/>lint-spec / scope-check / lint-tasks / lint-bindings / generate-sidecars / diff-spec / scaffold]
+  D --> F[Visual & Review<br/>icon-sync / icon-search / supervisor-review]
+  D --> G[Pen Files & Sync<br/>preflight-pencil / ensure-pen / write-pen / check-pen-sync / check-pen-baseline / sync-pen-source / snapshot-pen]
+  D --> H[Pencil Session<br/>pencil-lock * / pencil-session begin|persist|end|status]
+  D --> I[Verification & Completion<br/>verify-bindings / verify-implementation / verify-structure / verify-coverage / audit]
+  D --> J[Setup & Tooling<br/>install / uninstall / status / validate-assets / bootstrap-project]
+
+  E --> I
+  F --> G
+  G --> H
+  H --> E
+  I --> K{Ready to finish?}
+  K -->|No| C
+  K -->|Yes| L[Completion audit and terminal claim]
+```
+
+Use this as the quick mental model:
+
+- start from `Routing & Resume`
+- move into the phase that matches the current blockers
+- return to `Routing & Resume` whenever the workflow pauses or artifacts changed materially
+- only finish after the verification lane and completion audit are both clear
+
+Main keys:
+
+- `Up/Down` or `j/k`: move selection
+- `Enter` or `r`: run the selected command
+- `h`: inspect parameters for the selected command
+- `m`: edit the preview command first
+- `p`: change project path context
+- `c`: change or clear change-id context
+- `l`: toggle English / Chinese
+- `s`: toggle `--strict`
+- `J`: toggle `--json`
+- `e`: toggle `--continue-on-error`
+- `?`: open help
+- `q`: quit
+
+Recommended TUI usage:
+
+1. launch the TUI from the project root
+2. set or confirm project path and change-id in the header
+3. start with `workflow-status`
+4. run `next-step`
+5. move into `lint-spec` / `scope-check` / `tasks` / `verify-*` as needed
+6. for specialized Pencil commands, press `m` and fill the remaining placeholders before execution
+
+## Practical Shortcuts
+
+- inside the project root, you usually do not need `--project`
+- with one active change, you often do not need `--change`
+- use `workflow-status` and `next-step` as the standard re-entry pair after any pause
+- use the TUI when command recall is the main problem
+- use direct CLI commands when you already know the exact surface and want faster scripting

package/docs/workflow-overview.md

@@ -14,6 +14,7 @@ Use [pencil-rendering-workflow.md](/Users/xubo/x-skills/da-vinci/docs/pencil-ren
 Use [dv-command-reference.md](/Users/xubo/x-skills/da-vinci/docs/dv-command-reference.md) when you need route-by-route `dv:` command behavior, next-step recommendations, and verify rollback handling.
 Use [constraint-files.md](/Users/xubo/x-skills/da-vinci/docs/constraint-files.md) when you need a single map for project constraint files, hard-gate fields, and advisory guidance sections.
 Use [execution-chain-migration.md](/Users/xubo/x-skills/da-vinci/docs/execution-chain-migration.md) for sidecar, enforcement, persisted-state fallback, and scaffold migration guidance.
+Use [skill-usage.md](/Users/xubo/x-skills/da-vinci/docs/skill-usage.md) for an operator-facing guide to starting, pausing, resuming, and using the TUI.
 
 ## Core Contract
 

package/docs/zh-CN/dv-command-reference.md

@@ -39,6 +39,10 @@ Da Vinci 期望它们遵循工作流状态。
 
 这些命令不会替代 `dv:` 选路，但能显著提升设计执行质量：
 
+- `da-vinci tui [--project <path>] [--change <id>] [--lang en|zh]`
+  - 打开面向工作流的终端 UI，按阶段组织命令，并在执行前先展示生成出的 CLI 预览
+  - 也可以用独立 bin `da-vinci-tui`，或在没全局安装时用 `npx -p @xenonbyte/da-vinci-workflow da-vinci tui`
+  - 当真正难记的是命令面而不是流程本身时，优先用它
 - `da-vinci workflow-status --project <path> [--change <id>] [--json]`
   - 从工件和 checkpoint 真相推导当前 workflow 阶段
   - 报告 blocker、warning、handoff gate 状态，以及主推荐路由

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

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

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

@@ -0,0 +1,217 @@
+# 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 提供这些能力：
+
+- 按工作流阶段对命令分组
+- 中英文双语界面说明
+- 顶部显示当前项目路径和 change-id 上下文
+- 执行前可先看命令预览
+- 一键切换 `--strict`、`--json`、`--continue-on-error`
+- 对 `<pen-path>` 这类还没补具体路径的命令，支持先编辑预览再执行
+
+### 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 并做终态声明]
+```
+
+你可以把它理解成这四条最实用的规则：
+
+- 先从“选路与续跑”开始
+- 再进入当前 blocker 所在的阶段
+- 只要中途暂停，或者工件发生了实质变化，就回到“选路与续跑”
+- 只有验证链和 completion audit 都通过了，才进入终态
+
+主要按键：
+
+- `Up/Down` 或 `j/k`：移动选中项
+- `Enter` 或 `r`：执行当前命令
+- `h`：查看当前命令参数
+- `m`：先编辑预览命令
+- `p`：修改项目路径上下文
+- `c`：修改或清空 change-id 上下文
+- `l`：切换中英文
+- `s`：切换 `--strict`
+- `J`：切换 `--json`
+- `e`：切换 `--continue-on-error`
+- `?`：打开帮助
+- `q`：退出
+
+推荐的 TUI 使用顺序：
+
+1. 在项目根目录启动 TUI
+2. 先确认顶部的 project path 和 change-id
+3. 先跑 `workflow-status`
+4. 再跑 `next-step`
+5. 根据情况进入 `lint-spec`、`scope-check`、`tasks`、`verify-*`
+6. 如果是 Pencil 相关特殊命令，按 `m` 先把剩余占位符补全后再执行
+
+## 实用简化规则
+
+- 在项目根目录里，通常不需要写 `--project`
+- 只有一个 active change 时，通常也不需要写 `--change`
+- 每次暂停回来，默认先跑 `workflow-status` 和 `next-step`
+- 觉得命令太散时，用 TUI
+- 已经很清楚要跑哪条命令、而且在写脚本时，直接用 CLI 更快

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)。
 
 ## 核心契约