@xenonbyte/da-vinci-workflow 0.2.2 → 0.2.3

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

@@ -146,67 +146,74 @@ 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>`
+- 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 Phase Map
+### TUI Scene 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]
+  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 `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
+- 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`: run the selected command
-- `h`: inspect parameters for the selected command
-- `m`: edit the preview command first
+- `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
-- `q`: quit
+- `Ctrl-C`: emergency exit
 
 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
+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
 

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

@@ -157,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
 
@@ -166,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

@@ -101,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 的图标定稿前。
 
@@ -174,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`
 
 适合：
@@ -210,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`
 
 适合：
@@ -225,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 完成
@@ -245,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. 进入实现

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

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

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

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

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

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

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

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

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

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