@xenonbyte/da-vinci-workflow 0.1.16 → 0.1.17

package/CHANGELOG.md

@@ -1,16 +1,22 @@
 # Changelog
 
-## v0.1.16 - 2026-03-28
+## v0.1.17 - 2026-03-28
 
 ### Added
 - `da-vinci preflight-pencil` as a static preflight for non-trivial Pencil `batch_design` payloads, catching common syntax and schema drift before they hit MCP
 - `da-vinci write-pen` to atomically write a project-local `.pen` from MCP-readable node and variable snapshot data
-- `da-vinci snapshot-pen` to reopen an existing `.pen`, capture a fresh MCP-readable snapshot, and rewrite a canonical project-local `.pen` with reopen verification
+- `da-vinci ensure-pen` to seed or verify a registered project-local `.pen` before live editing starts
+- `da-vinci check-pen-sync` to compare a current live MCP snapshot payload against the persisted project-local `.pen`
+- `da-vinci pencil-lock` to serialize Pencil MCP write access across multiple projects on the same machine
+- `da-vinci pencil-session begin / persist / end / status` as the preferred session-level wrapper for seeded `.pen` ownership, persistence, sync checks, and lock release
+- `scripts/test-pencil-session.js` and `scripts/test-persistence-flows.js` to cover session lifecycle plus new/existing/parallel project flows
 
 ### Changed
 - active Pencil guidance now requires smaller anchor-surface batches, micro-batch fallback after repeated rollbacks, and structured screenshot-review records instead of self-affirming prose
 - design routes, prompt presets, workflow examples, and README guidance now call for `da-vinci audit --mode integrity <project-path>` immediately after the first successful Pencil write during active redesign work
-- project-local `.pen` persistence now treats headless interactive `save()` as non-authoritative; first-run sessions must persist the first approved live MCP snapshot, and resume sessions must overwrite the registered `.pen` from the current snapshot after material live edits
+- project-local `.pen` persistence now treats headless interactive `save()` as non-authoritative; redesign passes should seed the registered `.pen` before the first edit, then persist current live MCP snapshots back to that same path after material edits
+- `da-vinci snapshot-pen` is now documented and treated as a disk-to-disk utility only, not as a live-edit persistence step
+- completion audit now expects `.da-vinci/state/pencil-session.json` plus matching persisted snapshot hashes before completion can pass
 
 ## v0.1.15 - 2026-03-27
 

package/README.md

@@ -32,8 +32,11 @@ Latest published npm package:
 Release highlights:
 
 - project-local `.pen` persistence now uses an MCP-snapshot-to-disk path instead of relying on headless interactive `save()`
+- redesign runs now seed a registered project-local `.pen` before the first Pencil edit and record persisted snapshot hashes for later sync checks
 - `da-vinci write-pen` now atomically writes workflow-owned `.pen` files from MCP-readable node and variable payloads with optional reopen verification
-- `da-vinci snapshot-pen` now rebuilds a canonical local `.pen` from an existing Pencil source and verifies reopen with Pencil
+- `da-vinci ensure-pen` now seeds or verifies a registered project-local `.pen` before live editing starts
+- `da-vinci check-pen-sync` now compares a current live MCP snapshot payload against the persisted project-local `.pen`
+- `da-vinci snapshot-pen` now serves only as a disk-to-disk utility for rebuilding an existing Pencil source and verifying reopen
 - visual-adapter execution now requires explicit runtime declaration of the resolved primary adapter and any unavailable requested adapters
 - cross-platform near-name adapters such as `frontend-skill` and `frontend-design` are now treated as distinct unless the current environment explicitly resolves them
 - complex `redesign-from-code` runs now require a visual thesis, content plan, interaction thesis, and anchor-surface structural-delta notes before broad Pencil generation
@@ -447,15 +450,23 @@ During active redesign work, prefer running `da-vinci audit --mode integrity <pr
 
 Project-local `.pen` persistence now has two supported paths:
 
-- first-run path: if no registered project-local `.pen` exists yet, let the first approved anchor surface happen in the live editor, then persist that approved MCP snapshot under `.da-vinci/designs/`
-- resume path: if a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming interactive `save()` flushed it
+- first-run path: seed the registered project-local `.pen` with `da-vinci ensure-pen --output <path> --verify-open`, open that exact path, then persist later MCP snapshot writes back to the same file
+- resume path: if a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh live MCP snapshot back to that same path and run `da-vinci check-pen-sync`
 
 Persistence helpers:
 
+- preferred wrapper:
+  - `da-vinci pencil-session begin --project <project-path> --pen <path>`
+  - `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+  - `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci ensure-pen --output <path> --verify-open`
 - `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
-- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open`
+- `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open` (disk-to-disk only)
+- `da-vinci pencil-lock acquire --project <project-path>` / `da-vinci pencil-lock release --project <project-path>`
 
 Do not treat headless interactive `save()` as authoritative persistence truth until the underlying Pencil behavior is proven reliable again.
+Completion audit now also expects `.da-vinci/state/pencil-session.json` to reflect the latest persisted `.pen` hash, so autonomous runs should prefer the `pencil-session` wrapper.
 
 Installation targets:
 

package/README.zh-CN.md

@@ -34,8 +34,11 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 已发布版本重点：
 
 - 项目内 `.pen` 持久化现在改为“从 MCP 快照写回磁盘”的正式路径，不再依赖 headless interactive `save()`
+- 重设计流程现在要求在第一次 Pencil 编辑前先 seed 一个登记好的项目内 `.pen`，并记录后续持久化快照 hash 以便做同步校验
 - `da-vinci write-pen` 现在可以把 MCP 可读的节点和变量快照原子写成工作流管理的 `.pen` 文件，并可选地做 reopen 校验
-- `da-vinci snapshot-pen` 现在可以从现有 Pencil 源重建一个规范化的本地 `.pen`，并验证重新打开结果
+- `da-vinci ensure-pen` 现在可以在 live 编辑开始前 seed 或校验登记好的项目内 `.pen`
+- `da-vinci check-pen-sync` 现在可以把当前 live MCP 快照和已持久化的项目内 `.pen` 做同步比对
+- `da-vinci snapshot-pen` 现在只作为 disk-to-disk 工具，用来从已有 Pencil 源重建规范化 `.pen` 并验证重新打开结果
 - visual adapter 的执行现在要求在运行时明确声明解析出来的主 adapter，以及哪些请求的 adapter 当前不可用
 - `frontend-skill`、`frontend-design` 这类跨平台近名 adapter 现在明确视为不同能力源，除非当前环境真的解析到了它们
 - 复杂 `redesign-from-code` 现在要求在大规模 Pencil 设计前先写 visual thesis、content plan、interaction thesis 和 anchor surface 的 structural-delta 说明
@@ -376,16 +379,23 @@ da-vinci uninstall --platform codex,claude,gemini
 
 项目内 `.pen` 持久化现在分成两条受支持路径：
 
-- 首次运行路径：如果当前还没有登记的项目内 `.pen`，先允许第一个通过审查的 anchor surface 在 live editor 里完成，然后把这个 MCP 快照持久化到 `.da-vinci/designs/`
-- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 MCP 快照重新持久化回同一路径，而不是假设 interactive `save()` 已经刷回磁盘
+- 首次运行路径：先用 `da-vinci ensure-pen --output <path> --verify-open` seed 登记好的项目内 `.pen`，打开这个精确路径，然后把后续 MCP 快照持续写回同一个文件
+- 继续迭代路径：如果项目里原本已有登记的 `.pen`，先打开它继续工作；但发生实质性 live edit 后，要把当前 live MCP 快照重新持久化回同一路径，并运行 `da-vinci check-pen-sync`
 
 推荐使用的持久化命令：
 
+- 优先使用封装好的 session 命令：
+  - `da-vinci pencil-session begin --project <project-path> --pen <path>`
+  - `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+  - `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci ensure-pen --output <path> --verify-open`
 - `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open`
-- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open`
+- `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- `da-vinci snapshot-pen --input <existing.pen> --output <target.pen> --verify-open`（仅限 disk-to-disk）
+- `da-vinci pencil-lock acquire --project <project-path>` / `da-vinci pencil-lock release --project <project-path>`
 
 在 Pencil 底层 `save()` 语义再次被证明可靠之前，不要把 headless interactive `save()` 当作权威持久化真相。
-在重设计进行中，建议在第一次成功写入 Pencil 后立刻跑一次 `da-vinci audit --mode integrity <project-path>`；如果同一个 anchor surface 连续回滚两次，就配合 `da-vinci preflight-pencil` 改成更小的后续批次。
+completion audit 现在还会检查 `.da-vinci/state/pencil-session.json` 是否记录了最新的 `.pen` hash，所以自治运行优先走 `pencil-session` 封装。
 
 安装目标：
 

package/SKILL.md

@@ -229,12 +229,21 @@ During active Pencil work:
 - when shell access is available, preflight non-trivial `batch_design` operation strings before sending them to Pencil
 - prefer 12 or fewer operations on anchor-surface batches; if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
 - do not rely on headless interactive `save()` as the persistence truth; when live MCP edits exist, persist project-local `.pen` files from MCP-readable document snapshots
-- when no registered project-local `.pen` exists yet, let the first anchor work happen in the live editor, then persist the first complete MCP snapshot to the registered `.pen` path before broad expansion continues
-- when a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming live edits were flushed automatically
+- prefer the session wrapper commands:
+  `da-vinci pencil-session begin --project <project-path> --pen <path>`
+  `da-vinci pencil-session persist --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+  `da-vinci pencil-session end --project <project-path> --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>`
+- before the first Pencil edit on a redesign pass, begin a Pencil session so the registered project-local `.pen` exists before editing and the global Pencil lock is held for that project
+- acquire the global Pencil lock before MCP write operations on a project and release it after the write phase so two projects do not compete for the same active editor
+- when a registered project-local `.pen` already exists, reopen it for continuity, but after material live edits persist a fresh MCP snapshot back to that same path instead of assuming live edits were flushed automatically
+- `da-vinci snapshot-pen` is a disk-to-disk utility for rebuilding an existing `.pen`; do not use it as live-edit persistence
 - use `da-vinci write-pen --output <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version> --verify-open` to atomically write the registered project-local `.pen` from MCP snapshot data
+- after writing the project-local `.pen`, run `da-vinci check-pen-sync --pen <path> --nodes-file <batch-get-json> --variables-file <get-variables-json> --version <version>` before treating the disk source as current
+- completion audit expects a recorded Pencil session state under `.da-vinci/state/pencil-session.json`; do not bypass the session wrapper on autonomous runs
 - after the first successful Pencil write, verify that the registered project-local `.pen` path exists as a shell-visible file before treating the design source as persistent
 - after the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` when shell access is available before broad expansion continues
 - after the first successful Pencil write, run the MCP runtime gate when Pencil MCP is available and record the result in `pencil-design.md`
+- if the workflow already has a registered `.pen`, do not send Pencil write operations with an empty `filePath`
 - do not treat an unnamed live editor such as `new` as a persisted project design source; reconcile it to the registered project-local `.pen` path before the design pass is considered traceable
 - use only Pencil-supported properties; do not emit web- or CSS-only layout properties such as `flex` or `margin`
 - if unsupported Pencil properties cause repeated rolled-back batches on the same anchor surface, treat that pass as unstable and fix the schema usage before expanding further

package/commands/claude/dv/design.md

@@ -20,8 +20,9 @@ Create or update:
 Run the `design checkpoint` before locking implementation tasks.
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+Prefer the session wrapper commands: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Before the first Pencil edit, begin a Pencil session so the registered project-local `.pen` is seeded and locked before editing starts.
+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 `pencil-session persist` after material edits.
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` 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`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.

package/commands/codex/prompts/dv-design.md

@@ -14,8 +14,9 @@ Output should move the work toward:
 Use Pencil-backed structure as the design source when available.
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+Prefer the session wrapper commands: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Before the first Pencil edit, begin a Pencil session so the registered project-local `.pen` is seeded and locked before editing starts.
+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 `pencil-session persist` after material edits.
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` 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`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.

package/commands/gemini/dv/design.toml

@@ -13,8 +13,9 @@ Create or update:
 Use Pencil-backed page coverage as the source of presentation truth.
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+Prefer the session wrapper commands: `da-vinci pencil-session begin`, `da-vinci pencil-session persist`, and `da-vinci pencil-session end`.
+Before the first Pencil edit, begin a Pencil session so the registered project-local `.pen` is seeded and locked before editing starts.
+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 `pencil-session persist` after material edits.
 After the first successful Pencil write, run `da-vinci audit --mode integrity <project-path>` 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`.
 Screenshot review must record an explicit `PASS`, `WARN`, or `BLOCK` plus the issue list and revision outcome; "looks good" is not a valid review record.

package/docs/mode-use-cases.md

@@ -138,8 +138,8 @@ Generate DA-VINCI.md, proposal, specs, page map, Pencil-backed launch pages, bin
 
 8. create `pencil-design.md`
    - record the generated Pencil screens
-   - if no registered project-local `.pen` exists yet, persist the first approved MCP snapshot into the registered `.pen` path under `.da-vinci/designs/`
-   - if a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits
+   - prefer `da-vinci pencil-session begin` before the first Pencil edit so the registered `.pen` is seeded and locked up front
+   - if a registered project-local `.pen` already exists, reopen it for continuity but overwrite it from the current live MCP snapshot through `da-vinci pencil-session persist` after material live edits
    - keep screenshot exports under `.da-vinci/changes/<change-id>/exports/` rather than `.da-vinci/designs/`
 
 9. create `pencil-bindings.md`

package/docs/prompt-presets/README.md

@@ -14,7 +14,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, prefer prompts that distinguish first-run snapshot creation from resume/overwrite persistence instead of relying on interactive `save()`
+7. for project-local `.pen` persistence, prefer 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 cannot be used
 
 Available presets:
 

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

@@ -28,7 +28,7 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
 Inventory the current workspaces, dialogs, overlays, and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, 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.
 Do not pass design checkpoint if the result is just a boxed-up recolor of the old UI or if workspace hierarchy remains unclear.
@@ -55,7 +55,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`.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/`; if one already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
+Prefer `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.
 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.
 Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
@@ -76,7 +76,7 @@ Decompose complex screens into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the product is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
 Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Do not start code changes yet.
@@ -89,7 +89,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.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Reopen that file for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming interactive `save()` flushed it.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` when resuming, 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.
 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

@@ -28,7 +28,7 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current screens and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, 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.
 Do not pass design checkpoint if the result is a skin-swap of the old UI, a generic card grid, or a weak mobile hierarchy.
@@ -61,7 +61,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`.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/`; if one already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
+Prefer `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.
 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.
@@ -84,7 +84,7 @@ Decompose complex screens into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the app is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
 Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Do not start code changes yet.
@@ -97,7 +97,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.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Reopen that file for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming interactive `save()` flushed it.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` when resuming, 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.
 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

@@ -28,7 +28,7 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current tablet surfaces and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, 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.
 Do not pass design checkpoint if the result ignores tablet-scale composition or collapses into a stretched phone layout.
@@ -55,7 +55,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`.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/`; if one already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
+Prefer `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.
 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.
 Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
@@ -76,7 +76,7 @@ Decompose complex pages into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the product is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
 Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Do not start code changes yet.
@@ -89,7 +89,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.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Reopen that file for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming interactive `save()` flushed it.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` when resuming, 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.
 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

@@ -28,7 +28,7 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current business logic, routes, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current product surfaces and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and the global Pencil lock is held; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, 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.
 Do not pass design checkpoint if the result is a generic SaaS card grid or a recolor of the old interface.
@@ -56,7 +56,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`.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/`; if one already exists, reopen it for continuity but overwrite it from the current MCP snapshot after material live edits.
+Prefer `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.
 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.
 Do not report completion if the registered `.pen` source exists only in memory or only as exported PNGs.
@@ -77,7 +77,7 @@ Decompose complex pages into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the product is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
 Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
+Before the first Pencil edit, prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` so the registered project-local `.pen` is seeded and locked; fall back to `da-vinci ensure-pen --output <path> --verify-open` only when the session wrapper cannot be used.
 If Pencil MCP is active, run the MCP runtime gate after the first successful Pencil write and record it in `pencil-design.md`.
 Before reporting `design complete`, require both the MCP runtime gate and `da-vinci audit --mode completion --change <change-id> <project-path>` to pass.
 Do not start code changes yet.
@@ -90,7 +90,7 @@ $da-vinci use continue for this existing web-product redesign workflow.
 
 Use the existing Da Vinci artifacts in this project.
 Do not restart discovery unless an artifact is missing or clearly wrong.
-Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Reopen that file for continuity, but after material live edits persist a fresh MCP snapshot back to the same path instead of assuming interactive `save()` flushed it.
+Keep the registered project-local Pencil source under .da-vinci/designs/ as the design source of truth. Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` when resuming, 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.
 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/workflow-examples.md

@@ -84,8 +84,8 @@ Expected flow:
 8. create new or updated Pencil pages from fresh composition rather than a recolor of the old UI, preferring persistence under `.da-vinci/designs/`
 9. preflight non-trivial `batch_design` operation strings before sending them to Pencil, and keep anchor-surface batches small
 10. if the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds
-11. if no registered project-local `.pen` existed at the start of the session, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`
-12. if a registered project-local `.pen` already existed, reopen it for continuity and persist fresh MCP snapshots back to that same path after material live edits
+11. prefer `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
+12. during live design work, prefer `da-vinci pencil-session persist --project <project-path> --pen <path> ...` after material edits, then end with `da-vinci pencil-session end ...`
 13. verify the registered project-local `.pen` path becomes shell-visible immediately after the first successful Pencil write
 14. run `da-vinci audit --mode integrity <project-path>` immediately after that first successful write
 15. if Pencil MCP is active, run the MCP runtime gate and record it in `pencil-design.md`
@@ -116,8 +116,8 @@ Do not treat screenshot analysis as an automatic pass if it reports hierarchy, s
 Before non-trivial `batch_design` calls, preflight the Pencil operations when shell access is available.
 If the same anchor surface rolls back twice, switch to micro-batches of 6 or fewer operations until a clean schema-safe pass succeeds.
 Use only Pencil-supported properties; do not use web-only props like flex or margin.
-If no registered project-local `.pen` exists yet, persist the first approved MCP snapshot under `.da-vinci/designs/` instead of relying on interactive `save()`.
-If a registered project-local `.pen` already exists, reopen it for continuity but persist a fresh MCP snapshot back to that same path after material live edits.
+Prefer `da-vinci pencil-session begin --project <project-path> --pen <path>` before the first Pencil edit.
+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`.
 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.
@@ -160,7 +160,7 @@ Use the visual-adapter preferences declared in DA-VINCI.md.
 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, persist the first approved MCP snapshot there.
+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.
 ```
 

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

@@ -91,7 +91,7 @@ Da Vinci 应该：
    - 优先登记 `.da-vinci/designs/` 下的本地 `.pen` 路径
 7. 生成 `design.md`
 8. 生成 `pencil-design.md`
-   - 如果一开始还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果一开始还没有登记的项目内 `.pen`，先在登记好的 `.da-vinci/designs/` 路径 seed 一个 `.pen` 再开始第一次 Pencil 编辑
    - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
 9. 生成 `pencil-bindings.md`
 10. 生成 `tasks.md`
@@ -113,7 +113,7 @@ Da Vinci 应该：
 5. 生成 `specs/<capability>/spec.md`
 6. 生成 `page-map.md`
 7. 继续到设计、绑定、任务和实现
-   - 如果一开始还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果一开始还没有登记的项目内 `.pen`，先在登记好的 `.da-vinci/designs/` 路径 seed 一个 `.pen` 再开始第一次 Pencil 编辑
    - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
 
 ## 3. `redesign-from-code`
@@ -140,7 +140,7 @@ Da Vinci 应该：
    - 在大规模 anchor 设计前，先写 visual thesis、content plan、interaction thesis 和 structural-delta 说明
    - 先做 1 到 3 个 anchor surface，再扩展更多页面
    - 首轮设计由解析出来的主 visual adapter 主导
-   - 如果一开始还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 如果一开始还没有登记的项目内 `.pen`，先在登记好的 `.da-vinci/designs/` 路径 seed 一个 `.pen` 再开始第一次 Pencil 编辑
    - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
    - 在第一次成功写入 Pencil 后，立即验证登记的 `.pen` 路径已经成为 shell 可见文件
    - 截图导出必须写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`
@@ -170,7 +170,8 @@ Da Vinci 应该：
 - 一个实现页如果包含多个 Fragment、多个 tab、多个状态或多个 overlay，应该拆成多个设计 surface
 - `design-registry.md` 里的首选 `.pen` 路径由工作流自动维护，不应该依赖用户手工填写
 - 不要因为当前 Pencil 里正好打开了一个文档，就直接在那个文档上继续做重设计
-- 不要把 interactive `save()` 当作可靠的持久化真相；应从当前 MCP 可读快照重建并覆盖项目内 `.pen`
+- 不要把 interactive `save()` 当作可靠的持久化真相；应先 seed 项目内 `.pen`，然后从当前 MCP 可读快照重建并覆盖它，并通过 `da-vinci check-pen-sync` 做同步校验
+- 如果支持 CLI，优先走 `da-vinci pencil-session begin / persist / end`，不要再手拼 `ensure-pen + write-pen + lock`
 - 如果 Pencil MCP 没有自动把登记路径的 `.pen` 文件落到磁盘，就应该先补写这个项目内文件，再把 mapping 或 implementation 视为完成
 - `.da-vinci/designs/` 应该只作为 `.pen` 目录使用，不应该混入 inventory、proposal 之类的 markdown
 - 截图 PNG 只是审查产物，不能替代登记好的 `.pen` 设计源
@@ -190,8 +191,8 @@ Da Vinci 应该：
 4. 复用或更新 `design-registry.md`
    - 如果已有项目内 `.pen` 文件，优先登记 `.da-vinci/designs/` 下的路径
 5. 生成 `pencil-design.md` 增量
-   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径
-   - 如果这次改动还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照真正落到登记好的 `.da-vinci/designs/` 路径
+   - 优先通过 `da-vinci pencil-session begin` 开始这轮设计，让登记路径先 seed 好并拿到锁
+   - 如果项目里原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后优先通过 `da-vinci pencil-session persist` 把当前 MCP 快照重新覆盖写回同一路径
 6. 更新 `pencil-bindings.md`
 7. 生成 `tasks.md`
 8. 进入实现

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

@@ -14,7 +14,7 @@
 4. 两者一起放进工作流设置
 5. 只有在项目存在特殊真相源或平台约束时，再继续收紧提示词
 6. 如果 Pencil MCP 可用，优先使用已经明确要求 MCP runtime gate 和 completion audit 的那版 redesign 提示词
-7. 如果项目要把 `.pen` 真正持久化到本地，优先使用已经区分“首次生成快照”和“继续迭代覆盖保存”的那版提示词，不要依赖 interactive `save()`
+7. 如果项目要把 `.pen` 真正持久化到本地，优先使用要求 `da-vinci pencil-session begin / persist / end` 的提示词；只有 wrapper 不可用时再退回 `ensure-pen + write-pen + check-pen-sync`
 
 可用模板：
 

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

@@ -28,7 +28,7 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve current behavior, flows, integrations, and validation rules unless explicitly required otherwise.
 Inventory the current workspaces, dialogs, overlays, and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有全局 Pencil 锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 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>`。
 Do not pass design checkpoint if the result is just a boxed-up recolor of the old UI or if workspace hierarchy remains unclear.
@@ -55,7 +55,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`。
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
+在第一次 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` 这条底层链路。
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
 如果登记的 `.pen` 设计源只存在于内存中，或只剩下导出的 PNG，就不能宣布完成。
@@ -76,7 +76,7 @@ Decompose complex screens into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the product is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
 Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
 在声明 `design complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Do not start code changes yet.
@@ -89,7 +89,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.
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时优先执行 `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` 这条底层链路。
 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

@@ -28,7 +28,7 @@ Existing code is the behavior source of truth, not the layout truth.
 Preserve business logic, navigation, permissions, integrations, validations, and state transitions unless explicitly required otherwise.
 Inventory the current screens and important states before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有全局 Pencil 锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 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>`。
 Do not pass design checkpoint if the result is a skin-swap of the old UI, a generic card grid, or a weak mobile hierarchy.
@@ -61,7 +61,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`。
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`；如果原本已有 `.pen`，继续设计时先打开它，但发生实质性 live edit 后要把当前 MCP 快照重新覆盖写回同一路径。
+在第一次 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` 这条底层链路。
 Keep non-`.pen` workflow artifacts out of `.da-vinci/designs/`.
 截图导出只能写到 `.da-vinci/changes/<change-id>/exports/`，不能写进 `.da-vinci/designs/`。
 截图审查必须记录明确的 `PASS` / `WARN` / `BLOCK`、问题列表和是否回改；“看起来很好”不算审查记录。
@@ -84,7 +84,7 @@ Decompose complex screens into real design surfaces before Pencil work.
 Use the Visual Assist preferences declared in DA-VINCI.md.
 If the app is complex, design 1-3 anchor surfaces first, review screenshots, then expand.
 Stop after DA-VINCI.md, design-registry.md, page-map.md, proposal.md, specs, design.md, pencil-design.md, pencil-bindings.md, and tasks.md.
-如果当前还没有登记的项目内 `.pen`，先把第一个通过审查的 MCP 快照持久化到 `.da-vinci/designs/`，不要依赖 interactive `save()`。
+在第一次 Pencil 编辑前，优先执行 `da-vinci pencil-session begin --project <project-path> --pen <path>`，让登记好的项目内 `.pen` 先完成 seed 并持有锁；只有 session wrapper 不可用时，再退回 `da-vinci ensure-pen --output <path> --verify-open`。
 如果 Pencil MCP 可用，在第一次成功写入 Pencil 后运行 MCP runtime gate，并把结果记录到 `pencil-design.md`。
 在声明 `design complete` 之前，必须同时通过 MCP runtime gate 和 `da-vinci audit --mode completion --change <change-id> <project-path>`。
 Do not start code changes yet.
@@ -97,7 +97,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.
-把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时先打开这个文件，但发生实质性 live edit 后，要把当前 MCP 快照重新覆盖写回同一路径，不要假设 interactive `save()` 已经刷回磁盘。
+把登记的项目内 Pencil 源保持在 `.da-vinci/designs/` 下，作为设计真相源。继续设计时优先执行 `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` 这条底层链路。
 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>`。