@xenonbyte/da-vinci-workflow 0.2.1 → 0.2.3

package/docs/pencil-rendering-workflow.md

@@ -29,7 +29,7 @@ PNG exports are review artifacts only. They are not the design source of truth.
 Da Vinci now requires the session wrapper on autonomous runs:
 
 - `da-vinci pencil-session begin`
-- `da-vinci pencil-session persist`
+- `da-vinci save-current-design`
 - `da-vinci pencil-session end`
 
 This wrapper exists to make three things mandatory:
@@ -75,18 +75,21 @@ When resuming from existing artifacts:
 
 Da Vinci does not treat headless interactive `save()` as authoritative persistence truth.
 
-Instead, the persistence step is:
+Instead, the primary persistence step is:
 
-1. read MCP-readable node snapshot data
-2. read MCP-readable variable snapshot data
-3. write the project-local `.pen`
-4. reopen-verify it
-5. compare live snapshot and persisted snapshot hashes
+1. run `da-vinci save-current-design --project <project-path>`
+2. require one explicit result envelope: `saved`, `blocked`, or `unavailable`
+3. treat only `saved` as persisted success
+4. treat `blocked` as save-time source/lock/payload contract failure
+5. treat `unavailable` as MCP bridge/runtime capture absence (never as a successful save)
 
 Relevant commands:
 
-- `da-vinci write-pen`
-- `da-vinci check-pen-sync`
+- high-level: `da-vinci save-current-design`
+- low-level fallback: `da-vinci pencil-session persist`, `da-vinci write-pen`, `da-vinci check-pen-sync`
+
+The MVP safety guarantee is source-path convergence only: registered `.pen`, session `penPath`, and active editor path must converge.
+Exact window-instance identity remains out of scope until MCP exposes stable window/editor identifiers.
 
 `da-vinci snapshot-pen` is disk-to-disk only. It is not the live-edit persistence path.
 
@@ -251,7 +254,7 @@ Typical autonomous chain:
 1. `da-vinci pencil-session begin --project <project-path> --pen <path>`
 2. if external/secondary `.pen` files exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before edits; if diverged, sync the preferred source into `<project-pen>` first
 3. Pencil MCP edits
-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 when configured
@@ -278,13 +281,13 @@ flowchart TD
     K -- No --> F
     K -- Yes --> L{Design-supervisor review configured?}
     L -- Yes --> M[Run design-supervisor review on screenshots plus theme inputs]
-    L -- No --> N[pencil-session persist writes live MCP snapshot back to .pen]
+    L -- No --> N[save-current-design persists bound live snapshot back to .pen]
     M --> O{Require Supervisor Review?}
     O -- No --> N
     O -- Yes --> P{Review PASS or accepted WARN?}
     P -- No --> F
     P -- Yes --> N
-    N --> Q[check-pen-sync verifies live hash equals persisted hash]
+    N --> Q[save-current-design returns saved or a terminal blocker/unavailable result]
     Q --> R{design-source checkpoint and runtime gate pass?}
     R -- No --> F
     R -- Yes --> S{More design work needed?}

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/prompt-presets/README.md

@@ -21,7 +21,7 @@ Recommended flow:
 4. copy both into your workflow setup
 5. tighten the prompt further only when the project has unusual truth sources or platform constraints
 6. when Pencil MCP is active, prefer the redesign prompts that explicitly require an MCP runtime gate plus a completion audit before terminal completion claims
-7. for project-local `.pen` persistence on autonomous runs, require prompts that drive `da-vinci pencil-session begin / persist / end`; fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the wrapper truly cannot be used
+7. for project-local `.pen` persistence on autonomous runs, require prompts that drive `da-vinci pencil-session begin / save-current-design / end`; treat `saved`, `blocked`, and `unavailable` as distinct outcomes, and only fall back to lower-level payload persistence when high-level save is unavailable
 
 Available presets:
 

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

@@ -120,7 +120,7 @@ Before non-trivial `batch_design` calls, preflight the Pencil operations when sh
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Run `da-vinci audit --mode integrity <project-path>` after the first successful Pencil write before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
-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. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
+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; fall back to `pencil-session persist --nodes-file/--variables-file` only when the high-level save bridge is unavailable.
 Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
 Record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome; "looks good" is not enough.
 If `DA-VINCI.md` configures `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint, using screenshots plus Pencil variables and the design theses as inputs. If `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before broad expansion or terminal completion.
@@ -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/.
@@ -191,7 +191,7 @@ Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 Determine continuation routing from current artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
 If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only fall back to lower-level payload persistence when the high-level save bridge is unavailable.
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 If Pencil MCP is active and this session performs new Pencil writes, rerun the MCP runtime gate and record the refreshed result 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.

package/docs/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.
 Run `da-vinci audit --mode integrity <project-path>` after that first successful Pencil write before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
-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. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
+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; fall back to `pencil-session persist --nodes-file/--variables-file` only when the high-level save bridge is unavailable.
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.
 Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
 Record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome; "looks good" is not enough.
@@ -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/.
@@ -199,7 +199,7 @@ Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 Determine continuation routing from current artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
 If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only fall back to lower-level payload persistence when the high-level save bridge is unavailable.
 If the redesign is complex, keep the anchor-first flow until the design checkpoint passes.
 If Pencil MCP is active and this session performs new Pencil writes, rerun the MCP runtime gate and record the refreshed result 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.

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

@@ -120,7 +120,7 @@ Before non-trivial `batch_design` calls, preflight the Pencil operations when sh
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Run `da-vinci audit --mode integrity <project-path>` after the first successful Pencil write before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
-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. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
+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; fall back to `pencil-session persist --nodes-file/--variables-file` only when the high-level save bridge is unavailable.
 Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
 Record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome; "looks good" is not enough.
 If `DA-VINCI.md` configures `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint, using screenshots plus Pencil variables and the design theses as inputs. If `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before broad expansion or terminal completion.
@@ -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/.
@@ -191,7 +191,7 @@ Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 Determine continuation routing from current artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
 If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only fall back to lower-level payload persistence when the high-level save bridge is unavailable.
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 If Pencil MCP is active and this session performs new Pencil writes, rerun the MCP runtime gate and record the refreshed result 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.

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

@@ -121,7 +121,7 @@ Before non-trivial `batch_design` calls, preflight the Pencil operations when sh
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Run `da-vinci audit --mode integrity <project-path>` after the first successful Pencil write before broad expansion continues.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
-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. Fall back to the lower-level `ensure-pen + write-pen + check-pen-sync` chain only when the session wrapper cannot be used.
+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; fall back to `pencil-session persist --nodes-file/--variables-file` only when the high-level save bridge is unavailable.
 Write exported screenshots under `.da-vinci/changes/<change-id>/exports/` only.
 Record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome; "looks good" is not enough.
 If `DA-VINCI.md` configures `Design-supervisor reviewers`, run `design-supervisor review` after screenshot review, layout hygiene, and design checkpoint, using screenshots plus Pencil variables and the design theses as inputs. If `Require Supervisor Review: true`, treat missing, blocked, or unaccepted review results as blocking before broad expansion or terminal completion.
@@ -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/.
@@ -192,7 +192,7 @@ Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
 Determine continuation routing from current artifact and checkpoint truth first, then use contextual checkpoint deltas only as auxiliary recovery notes.
 If a contextual delta conflicts with current artifacts, ignore that delta and record the conflict before continuing.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material live edits; fall back to the lower-level `write-pen + check-pen-sync` path only when the session wrapper cannot be used.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. If the resumed session will perform Pencil edits, require `da-vinci pencil-session begin --project <project-path> --pen <path>`, then use `da-vinci save-current-design --project <project-path>` after material live edits. Treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only fall back to lower-level payload persistence when the high-level save bridge is unavailable.
 If the redesign is complex, continue from the approved anchor surfaces instead of restarting broad scaffolding.
 If Pencil MCP is active and this session performs new Pencil writes, rerun the MCP runtime gate and record the refreshed result 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.

package/docs/skill-usage.md

@@ -0,0 +1,224 @@
+# 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:
+
+- a scene-first landing screen with `Install & Uninstall`, `Current Status`, `Switch Work Item`, `Design Ops`, `Pre-Implementation Checks`, `Pre-Acceptance Checks`, and `Settings`
+- guided compound flows for resume, implementation readiness, and completion validation
+- `Design Ops` focuses on practical design operations (`Save Current Design`, `Sync Icon Library`, and `Visual Assist Preset`)
+- `Install & Uninstall` provides three actions: `Status` (show `da-vinci status`), `Install` (install all supported platforms), and `Uninstall` (uninstall all supported platforms)
+- English and Chinese chrome while keeping emitted Visual Assist content in canonical English
+- project/change context in the header with minimal persistent chrome
+- `Settings` keeps only `Language` and `Logs`
+- project-local daily diagnostics under `Settings > Logs` (`.da-vinci/logs/YYYY-MM-DD.ndjson`)
+
+### TUI Scene Map
+
+```mermaid
+flowchart TD
+  A[Launch da-vinci tui] --> B[Set project path and change context]
+  B --> C[Install & Uninstall<br/>status + install-all + uninstall-all]
+  B --> D[Current Status<br/>workflow-status + next-step summary]
+  B --> E[Switch Work Item<br/>pick an existing change]
+  B --> F[Design Ops<br/>icon sync + visual assist preset]
+  B --> G[Pre-Implementation Checks<br/>implementation readiness gate]
+  B --> H[Pre-Acceptance Checks<br/>verify-* chain]
+  B --> I[Settings<br/>language + logs]
+```
+
+Use this as the quick mental model:
+
+- start from the scene that matches the current operator moment
+- let the scene entrypoints orchestrate the common checks first
+- use `Current Status` when a workflow pauses or the next route is unclear
+- finish only after `Pre-Acceptance Checks` is clear
+
+Visual Assist Preset mapping (`Design Ops > Visual Assist Preset`):
+
+- `Masterpiece` => `required reviewer signoff`
+- `High Quality` => `advisory reviewer`
+- `Normal` => `adapter-only`
+
+Managed Visual Assist behavior:
+
+- select platform first, then select one of 3 quality levels
+- write canonical English output from `docs/visual-assist-presets/`
+- replace only `## Visual Assist` in project-root `DA-VINCI.md`
+- preserve unrelated sections and avoid duplicate `## Visual Assist` blocks
+
+Main keys:
+
+- `Up/Down` or `j/k`: move selection
+- `Enter` or `r`: open selected scene / action
+- `u/d`: page up / page down in long content views
+- `g/G`: jump to top / bottom in long content views
+- `p`: change project path context
+- `c`: change or clear change-id context
+- `l`: toggle English / Chinese
+- `t`: cycle between theme modes when auto-detection is wrong
+- `s`: toggle `--strict`
+- `J`: toggle `--json`
+- `e`: toggle `--continue-on-error`
+- `?`: open help
+- `Ctrl-C`: emergency exit
+
+Recommended TUI usage:
+
+1. launch the TUI from the project root
+2. pick the workflow scene that matches your current moment
+3. set or confirm project path and change-id in the header
+4. use the scene entrypoints first (`Switch Work Item`, `Pre-Implementation Checks`, `Install & Uninstall`, `Pre-Acceptance Checks`) and use `Current Status` as the direct re-entry summary
+5. use `Design Ops > Visual Assist Preset` to select platform + quality and write managed `Visual Assist` blocks
+6. use `Install & Uninstall > Status` to inspect installation state, or run `Install`/`Uninstall` for all supported platforms in one step
+7. inspect/copy diagnostics from `Settings > Logs` when troubleshooting; keep logs as evidence only, not routing truth
+
+## 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-examples.md

@@ -99,17 +99,19 @@ Expected flow:
 11. if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
 12. require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit so the registered `.pen` is seeded and the global Pencil lock is held
 13. when external or secondary `.pen` sources exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` before the new session write phase; if diverged, sync the chosen source into `<project-pen>` first
-14. during live design work, use `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material edits, then end with `da-vinci pencil-session end ...`
-15. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
-16. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
-17. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
-18. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
-19. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
-20. record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome before broad expansion
-21. bind routes and pages to Pencil screens
-22. generate tasks aligned to the redesign slices
-23. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
-24. build and verify only after the completion gate can eventually pass
+14. during live design work, use `da-vinci save-current-design --project <project-path>` after material edits, then end with `da-vinci pencil-session end ...`
+15. treat `saved`, `blocked`, and `unavailable` as distinct outcomes; only `saved` means the design source was persisted
+16. if save returns `unavailable`, do not claim success; use the lower-level `pencil-session persist --nodes-file/--variables-file` path only when the high-level bridge is unavailable
+17. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
+18. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
+19. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
+20. run `design-source checkpoint` to confirm the registered project-local `.pen` path, the active Pencil source, and the shell-visible file all agree
+21. export screenshots only under `.da-vinci/changes/<change-id>/exports/`, never into `.da-vinci/designs/`
+22. record screenshot review with explicit `PASS` / `WARN` / `BLOCK`, issue list, and revision outcome before broad expansion
+23. bind routes and pages to Pencil screens
+24. generate tasks aligned to the redesign slices
+25. run `da-vinci audit --mode completion --change <change-id> <project-path>` before any terminal completion claim
+26. build and verify only after the completion gate can eventually pass
 
 ### Complex Android example
 
@@ -134,7 +136,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.
 Require `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit.
 When external or secondary `.pen` files exist, run `da-vinci check-pen-baseline --pen <project-pen> --baseline <other-pen>` first; if hashes diverge, sync the preferred source into `<project-pen>` before editing.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh live MCP snapshot back to that same path through `da-vinci pencil-session persist`.
+If a registered project-local `.pen` already exists, reopen it for continuity and save through `da-vinci save-current-design --project <project-path>`.
+Treat `saved`, `blocked`, and `unavailable` as distinct outcomes. If `unavailable`, do not claim success and only then fall back to the lower-level `pencil-session persist` payload path.
 Verify the registered project-local `.pen` file exists as a shell-visible file after the first Pencil write.
 Run `da-vinci audit --mode integrity <project-path>` after that first successful Pencil write before broad expansion continues.
 Keep `.da-vinci/designs/` reserved for `.pen` files only.
@@ -201,7 +204,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/.
 If no registered project-local `.pen` exists yet, seed it there before the first Pencil edit and keep subsequent live edits bound to that exact path.
-If a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
+If a registered project-local `.pen` already exists, reopen it for continuity and persist after material live edits through `da-vinci save-current-design --project <project-path>`.
 ```
 
 ## Icon-library helper example

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
 
@@ -156,6 +157,7 @@ Before mapping or implementation are treated as safe, Da Vinci runs:
 
 - `design-source checkpoint`
 - `MCP runtime gate` when Pencil MCP is active
+- `da-vinci save-current-design --project <project-path>` after material live edits (high-level bound-source save path)
 - `da-vinci audit --mode integrity <project-path>` during active work
 - checkpoint-adjacent `Context Delta` notes in existing change artifacts
 
@@ -165,6 +167,7 @@ These checks verify that:
 - the active editor is the correct source
 - the shell-visible `.pen` exists
 - live snapshot and persisted snapshot are in sync
+- high-level save outcomes are handled honestly (`saved` / `blocked` / `unavailable`)
 - recent execution context is recoverable without replacing artifact truth as the routing authority
 
 ### 6. Mapping

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 状态，以及主推荐路由
@@ -97,6 +101,11 @@ Da Vinci 期望它们遵循工作流状态。
 - `da-vinci sync-pen-source --from <preferred-source> --to <project-pen>`
   - 把被选中的最新 `.pen` 来源同步到项目内 `.pen` 路径，并刷新 Da Vinci state 元数据
   - 当外部备份是最新基线时，在 `pencil-session begin` 前先执行
+- `da-vinci save-current-design --project <path> [--json] [--continue-on-error]`
+  - 运行高层绑定源保存流程，作为 guided 设计持久化主路径
+  - 持久化前必须确认 registered `.pen`、session `penPath`、active editor path 收敛到同一来源
+  - 统一返回 `saved` / `blocked` / `unavailable`
+  - `blocked` 表示保存契约失败（来源/锁/载荷）；`unavailable` 表示 MCP bridge 或 runtime 抓取不可达
 
 建议在 `/dv:design` 阶段使用，尤其是在 anchor surface 的图标定稿前。
 
@@ -170,6 +179,14 @@ Da Vinci 期望它们遵循工作流状态。
 
 这一层负责塑造行为真相。
 
+需求拆解阶段自检：
+
+- 在把 requirements 交给设计前，先跑 `da-vinci workflow-status --project <path> [--change <id>] --json`
+- 再跑 `da-vinci next-step --project <path> [--change <id>]`
+- 跑 `da-vinci lint-spec --project <path> [--change <id>] --strict`
+- 把命令结果当成门禁，不要把 `BLOCK` 或非零退出码解释成软建议
+- 如果主推荐路由仍然是 `/dv:breakdown`，就继续修 `proposal.md` 和 specs，不要硬推进到 `/dv:design`
+
 ### `/dv:design`
 
 适合：
@@ -206,6 +223,14 @@ Da Vinci 期望它们遵循工作流状态。
 
 这一层只做实现拆解，不写代码。
 
+任务阶段自检：
+
+- 在把工作移交给实现前，先跑 `task checkpoint`
+- 有 shell 能力时，跑 `da-vinci lint-tasks --project <path> [--change <id>]`
+- 如果 `pencil-design.md` 和 `pencil-bindings.md` 都存在，再跑 `da-vinci lint-bindings --project <path> [--change <id>]`
+- 把命令结果当成门禁，不要把 `BLOCK` 或非零退出码降级成软提示
+- 只要任务覆盖或 bindings 就绪度仍然阻塞，就不要推进到 `/dv:build`
+
 ### `/dv:build`
 
 适合：
@@ -221,6 +246,18 @@ Da Vinci 期望它们遵循工作流状态。
 
 这一层才是真正的执行阶段。
 
+实现阶段自检：
+
+- 在大范围实现前，先跑 `da-vinci workflow-status --project <path> [--change <id>] --json`
+- 再跑 `da-vinci next-step --project <path> [--change <id>]`
+- 如果主推荐路由不是 `/dv:build`，就停止并回到那个路由，而不是硬做实现
+- 跑 `da-vinci lint-spec --project <path> [--change <id>]`
+- 跑 `da-vinci scope-check --project <path> [--change <id>]`
+- 如果 `tasks.md` 已存在，跑 `da-vinci lint-tasks --project <path> [--change <id>]`
+- 如果 `pencil-design.md` 和 `pencil-bindings.md` 都存在，跑 `da-vinci lint-bindings --project <path> [--change <id>]`
+- 把命令结果当成门禁，不要把 `BLOCK` 或非零退出码降级成软提示
+- 只要还有 `BLOCK` 或缺少必要 planning/design 工件，就不要进入大范围实现
+
 完成判定规则：
 
 - `BUILD SUCCESSFUL` 只代表可编译，不代表 workflow 完成
@@ -241,6 +278,16 @@ Da Vinci 期望它们遵循工作流状态。
 
 这一层是 truth reconciliation 阶段。
 
+验证阶段自检：
+
+- 有 shell 能力时，跑 `da-vinci verify-bindings --project <path> [--change <id>]`
+- 跑 `da-vinci verify-implementation --project <path> [--change <id>]`
+- 跑 `da-vinci verify-structure --project <path> [--change <id>]`
+- 跑 `da-vinci verify-coverage --project <path> [--change <id>]`
+- 把命令结果当成门禁，不要把 `BLOCK` 或 `FAIL` 降级成软提示
+- 只要任何验证面仍然是 `BLOCK` 或 `FAIL`，就继续停留在验证阶段并记录 drift，而不是宣称成功
+- 如果要声称终态完成，先要求 `da-vinci audit --mode completion --change <change-id> <project-path>` 通过
+
 ## 基于状态的下一步规则
 
 这就是当前应该给用户的推荐逻辑。

package/docs/zh-CN/mode-use-cases.md

@@ -239,7 +239,8 @@ Da Vinci 应该：
    - 如果已有项目内 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 5. 生成 `pencil-design.md` 增量
    - 必须通过 `da-vinci pencil-session begin` 开始这轮设计，让登记路径先 seed 好并拿到锁
-   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后优先执行 `da-vinci save-current-design --project <project-path>`
+   - 必须区分 `saved`、`blocked`、`unavailable` 三类结果；只有高层桥接 `unavailable` 时，才退回 `pencil-session persist --nodes-file/--variables-file` 的底层链路
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`
 8. 进入实现